Tairon-ai/aave-mcp

🚀 Features

🎯 Complete DeFi Protocol Integration

• Full Aave V3 lending protocol support on Base network
• Smart contract interactions with automatic gas optimization
• Real-time APY tracking and yield analytics
• Health factor monitoring and liquidation alerts
• Transaction simulation before execution

🧠 Intelligent Token Management

• Support for 16+ tokens including stablecoins, LSTs, and wrapped assets
• Automatic token detection and balance management
• Smart routing through 1inch DEX aggregator
• Fallback to Uniswap V3 with multi-tier fee optimization
• Slippage protection and MEV resistance

🤖 MCP Protocol Implementation

• 22 specialized tools for DeFi automation
• Compatible with AI assistants and automation frameworks
• HTTP/SSE and stdio transport support
• Real-time transaction execution with automatic signing
• Comprehensive error handling and retry logic

🏛️ Enterprise-Ready Architecture

• Built with NestJS for scalability and maintainability
• TypeScript for type safety and developer experience
• Modular service architecture for easy extension
• Comprehensive logging and monitoring
• Docker support for containerized deployment

📦 Quick Start

✅ Prerequisites

# Required
Node.js >= 18.0.0
npm or pnpm package manager

# Optional
Docker & Docker Compose (for containerized deployment)
Private key for transaction execution

📥 Installation

# Clone the repository
git clone https://github.com/Tairon-ai/aave-mcp.git
cd aave-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start the server
npm run start

# Development mode with hot reload
npm run start:dev

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

🛠 Available Tools

🏦 Aave Protocol Operations

💱 Token Swapping

🧠 Smart Operations

⛓️ Blockchain Utilities

🔗 API Endpoints

🌐 Core Endpoints

GET  /           # Server status and info
GET  /health     # Health check
GET  /mcp        # MCP server information
POST /mcp        # MCP protocol endpoint
GET  /mcp/tools  # List available tools
GET  /mcp/health # MCP health status

📡 WebSocket/SSE Support

GET /mcp/sse     # Server-Sent Events for real-time updates

💡 Examples

💰 Supply Tokens to Aave

// Supply 100 USDC to Aave
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "aave_stake",
    "arguments": {
      "asset": "USDC",
      "amount": "100",
      "userAddress": "0x..."
    }
  },
  "id": 1
}

🎯 Smart Stake with Auto-Funding

// Automatically swap ETH to USDC and stake
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "smart_stake_auto_fund",
    "arguments": {
      "targetToken": "USDC",
      "amount": "1000",
      "userAddress": "0x...",
      "slippageTolerance": 0.5
    }
  },
  "id": 1
}

📊 Get Best Swap Quote

// Get quote for swapping 1 ETH to USDC
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "oneinch_quote",
    "arguments": {
      "src": "ETH",
      "dst": "USDC",
      "amount": "1"
    }
  },
  "id": 1
}

🤖 Prompts

💬 Example Prompts for Claude, ChatGPT, or Other AI Assistants

These prompts demonstrate how to interact with the MCP server through natural language when integrated with AI assistants:

💼 DeFi Portfolio Management

"Check my DeFi portfolio balance at address 0x... and show me all token holdings"

"What's my current health factor on Aave? I have positions at 0x..."

"Calculate the best yield strategy for 10,000 USDC - should I supply to Aave or keep it liquid?"

"Show me my borrowing capacity if I deposit 5 ETH as collateral"

🏦 Lending & Borrowing Operations

"I want to supply 1000 USDC to Aave to earn yield. My address is 0x..."

"Help me borrow 500 DAI against my supplied ETH collateral at 0x..."

"What's the current APY for supplying WETH on Aave?"

"I need to repay my USDC loan on Aave. Show me my current debt and repay it all"

"Withdraw half of my supplied cbETH from Aave lending pool"

🔄 Token Swapping & Optimization

"Find the best route to swap 2 ETH to USDC using either Uniswap or 1inch"

"I have 5000 DAI and want to convert it to USDT with minimal slippage"

"Compare rates between Uniswap and 1inch for swapping 10 WETH to USDC"

"Execute a swap of 0.5 ETH to GHO token with maximum 1% slippage"

🚀 Smart Staking Strategies

"I want to stake USDC but only have ETH. Can you swap and stake 1000 USDC worth automatically?"

"Help me stake 2000 USDT using the smart staking feature - find the best yield"

"Auto-fund and stake 500 DAI from my available balance, swapping if needed"

"What's the optimal staking strategy for 10 ETH to maximize yield?"

🚮 Risk Management & Analytics

"Alert me if my health factor drops below 1.5 on Aave"

"Calculate liquidation price if I borrow 2000 USDC against 1 ETH collateral"

"Show me a risk analysis for borrowing 50% of my collateral value"

"What's my net APY considering both supply and borrow positions?"

📤 Transaction Management

"Simulate a transaction to supply 1000 USDC before executing it"

"Check current gas prices on Base network and estimate transaction costs"

"Prepare a batch transaction to: 1) Swap ETH to USDC, 2) Supply USDC to Aave"

"Show me my last 10 transactions on Aave protocol"

🎯 Complex DeFi Strategies

"Help me execute a leveraged yield farming strategy with 5000 USDC"

"I want to loop my ETH position - borrow USDC, swap to ETH, and resupply 3 times"

"Create a delta-neutral position by supplying ETH and borrowing equivalent USDC"

"Optimize my portfolio for maximum yield while maintaining health factor above 2"

📈 Market Analysis

"Compare current lending rates across all supported stablecoins"

"Which asset has the highest supply APY on Aave right now?"

"Show me utilization rates for all borrowable assets"

"What's the total value locked in Aave on Base network?"

🔧 Integration Tips for AI Assistants

When using these prompts with the MCP server:

1. Always specify the user address when performing wallet-specific operations
2. Set appropriate slippage tolerance (typically 0.5-2%) for swaps
3. Use simulation mode first for testing complex transactions
4. Monitor gas prices before executing large transactions
5. Check health factor before and after borrowing operations

🗺️ Natural Language to Tool Mapping

🧪 Testing

🧪 Manual Testing

# Test server connectivity
curl http://localhost:8080/health

# Get MCP server info
curl http://localhost:8080/mcp

# List all available tools
curl http://localhost:8080/mcp/tools

🔍 API Testing with cURL

# Check token balance
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_balance",
      "arguments": {
        "token": "USDC",
        "address": "0x..."
      }
    },
    "id": 1
  }'

🔒 Security

🔐 Best Practices

• Private Key Management: Never commit private keys. Use environment variables or secure key management systems
• Transaction Simulation: Always test transactions in simulation mode first (AUTO_EXECUTE=false)
• Slippage Protection: Set appropriate slippage limits (typically 0.5-2%)
• Gas Management: Monitor gas prices and set reasonable limits
• Access Control: Implement proper authentication for production deployments
• Monitoring: Use BaseScan and monitoring tools to track transactions

🛡️ Security Features

• Automatic gas estimation with configurable buffer
• Transaction simulation before execution
• Slippage protection on all swaps
• MEV protection through private mempools (when configured)
• Rate limiting and request validation
• Comprehensive error handling and logging

📊 Supported Networks & Tokens

🌐 Network

• Base Mainnet (Chain ID: 8453)
• RPC: https://base-rpc.publicnode.com

🪙 Supported Tokens

Stablecoins

• USDC, USDbC, USDT, DAI, GHO, EURC

ETH & Liquid Staking Tokens

• ETH, WETH, cbETH, wstETH, weETH, ezETH, wrsETH

Bitcoin Wrapped

• cbBTC, LBTC

Governance

• AAVE

📜 Key Contracts

• Aave V3 Pool: 0xA238Dd80C259a72e81d7e4664a9801593F98d1c5
• Uniswap V3 Router: 0x2626664c2603336E57B271c5C0b26F421741e481

🚀 Deployment

🏭 Production Deployment

# Build for production
npm run build

# Start production server
npm run start:prod

# With PM2
pm2 start dist/main.js --name aave-mcp

# With Docker
docker build -t aave-mcp .
docker run -d -p 8080:8080 --env-file .env aave-mcp

🔑 Environment Variables

# Required
PORT=8080
RPC_URL=https://base-rpc.publicnode.com
CHAIN_ID=8453
PRIVATE_KEY=your_private_key_without_0x

# Optional
LOG_LEVEL=info
AUTO_EXECUTE=true
ONE_INCH_API_KEY=your_api_key
TEST_WALLET_ADDRESS=0x...

📈 Performance

• Response Time: <100ms for read operations
• Transaction Speed: ~2s on Base network
• Throughput: 1000+ requests per second
• Uptime: 99.9% availability target
• Gas Optimization: Automatic batching and optimization

🤝 Contributing

We welcome contributions! Please see our for details.

# Fork and clone
git fork https://github.com/Tairon-ai/aave-mcp
git clone https://github.com/Tairon-ai/aave-mcp

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
npm run test
npm run lint

# Commit and push
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Aave Protocol - Leading DeFi lending protocol
• Base Network - Ethereum L2 scaling solution
• 1inch Network - DEX aggregation protocol
• Uniswap - Decentralized exchange protocol
• Model Context Protocol - AI integration standard
• NestJS - Progressive Node.js framework