<div align="center">

🌐 Aerodrome Finance MCP Server v0.1

Production-ready Model Context Protocol (MCP) server for Aerodrome Finance DEX operations on Base chain

Features • Quick Start • API • Tools • Examples • Prompts • Security

</div>

---

🚀 Features

🎯 Complete DEX Integration

• Full Aerodrome Finance V2 DEX support with concentrated liquidity
• Real-time token swaps with slippage protection
• Liquidity pool management and analytics
• Multi-route path optimization for best rates
• Gas-optimized transactions on Base chain
• Support for stable and volatile pools

🧠 Intelligent Trading Engine

• Smart routing through multiple DEX pools
• Automatic token detection and validation
• Real-time price feeds and quotes
• Slippage protection and MEV resistance
• Transaction simulation before execution
• Price impact calculations

🤖 MCP Protocol Implementation

• 11+ specialized tools for DEX automation
• Compatible with Claude Desktop and AI assistants
• HTTP and stdio transport support
• Real-time transaction execution
• Comprehensive error handling and retry logic
• Structured responses optimized for LLMs

🏛️ Enterprise-Ready Architecture

• Built with Express.js for scalability
• Ethers.js v5 for blockchain interactions
• Zod schemas for input validation
• Docker containerization support
• Comprehensive logging and monitoring
• Production-tested components

---

📦 Quick Start

✅ Prerequisites

# Required
Node.js >= 18.0.0
npm >= 9.0.0

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

📥 Installation

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

# Install dependencies
npm install

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

# Start the server
npm start

# Development mode
npm run dev

# MCP stdio server for Claude Desktop
npm run mcp

🐳 Docker Deployment

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

# View logs
docker-compose logs -f

# Stop services
docker-compose down

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "aerodrome-finance": {
      "command": "node",
      "args": ["/path/to/aerodrome-finance-mcp/mcp/index.js"],
      "env": {
        "BASE_RPC_URL": "https://mainnet.base.org",
        "WALLET_PRIVATE_KEY": "your_private_key_without_0x"
      }
    }
  }
}

---

🛠 Available Tools

🏦 DEX Operations

Tool	Description	Parameters
getServiceInfo	Get server capabilities and config	-
getTokenInfo	Get token details (symbol, decimals, supply)	tokenAddress
getPoolInfo	Get pool analytics (reserves, TVL)	poolAddress
getPoolByTokens	Find pools by token pair	tokenA, tokenB, stable
getAllPools	List all available pools	limit
getQuote	Get detailed swap quote	tokenIn, tokenOut, amountIn, stable
getQuoteSimple	Get quick price estimate	tokenIn, tokenOut, amountIn
getQuoteRest	Get accurate quote via REST	tokenIn, tokenOut, amountIn, stable
executeSwap	Execute token swap	tokenIn, tokenOut, amountIn, slippage, deadline
addLiquidity	Add liquidity to pool	tokenA, tokenB, amountA, amountB, stable
getWalletBalances	Get wallet token balances	walletAddress, tokens

---

🔗 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

---

💡 Examples

💰 Get Token Information

// Get USDC token details
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "getTokenInfo",
    "arguments": {
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  },
  "id": 1
}

🔄 Execute Swap

// Swap 1000 USDC for WETH
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "executeSwap",
    "arguments": {
      "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000",
      "slippage": 0.5,
      "deadline": 20
    }
  },
  "id": 1
}

📊 Get Swap Quote

// Get quote for swapping 1 ETH to USDC
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "getQuoteRest",
    "arguments": {
      "tokenIn": "0x4200000000000000000000000000000000000006",
      "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amountIn": "1.0",
      "stable": false
    }
  },
  "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:

💱 Token Swapping

"What's the current price of ETH in USDC on Aerodrome?"

"Swap 100 USDC to AERO tokens with 0.5% slippage"

"Execute a swap of 0.5 ETH to USDC with maximum slippage protection"

"Find the best route to swap 10,000 USDC to WETH"

💧 Liquidity Management

"Add liquidity to the WETH/USDC pool with 1 ETH and equivalent USDC"

"What's the current TVL in the WETH/USDC volatile pool?"

"Show me the top 10 pools by volume on Aerodrome"

"Calculate the optimal ratio for adding liquidity to AERO/USDC"

📊 Market Analysis

"Get the 24h volume for WETH/USDC pair"

"Show me all available pools for AERO token"

"What's the price impact of swapping 50 ETH to USDC?"

"Compare rates between stable and volatile pools for USDC/DAI"

💼 Portfolio Management

"Check my wallet balances for all tokens"

"What's my total portfolio value in USD?"

"Show me my liquidity positions and their current values"

"Monitor my transactions on Base chain"

🔧 Integration Tips for AI Assistants

When using these prompts with the MCP server:

1. Always specify token addresses or symbols for accurate operations
2. Set appropriate slippage (typically 0.5-2%)
3. Monitor gas prices before large transactions
4. Check balances before attempting swaps
5. Use quotes first before executing actual swaps

---

🧪 Testing

🔍 API Testing with cURL

# Check server health
curl http://localhost:8080/health

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

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

# Execute a tool
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "getTokenInfo",
      "arguments": {
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    },
    "id": 1
  }'

---

🔒 Security

🔐 Best Practices

• Private Key Management: Never commit private keys. Use environment variables
• Transaction Simulation: Test operations before execution
• Slippage Protection: Set appropriate limits (typically 0.5-2%)
• Gas Management: Monitor gas prices and set reasonable limits
• Access Control: Implement authentication for production
• Monitoring: Use Basescan to track all transactions

🛡️ Security Features

• Automatic gas estimation with buffer
• Transaction simulation before execution
• Slippage protection on all swaps
• Input validation with Zod schemas
• Comprehensive error handling
• Rate limiting support

---

📊 Supported Networks & Tokens

🌐 Network

• Base Mainnet (Chain ID: 8453)
• RPC: https://mainnet.base.org
• Explorer: Basescan

🪙 Key Tokens

• WETH: 0x4200000000000000000000000000000000000006
• AERO: 0x940181a94A35A4569E4529A3CDfB74e38FD98631
• USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• DAI: 0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb

📜 Key Contracts

• Router: 0xcF77a3Ba9A5CA399B7c97c74d54e5b1Beb874E43
• Factory: 0x420DD381b31aEf6683db6B902084cB0FFECe40Da
• Voter: 0x16613524e02ad97eDfeF371bC883F2F5d6C480A5

---

🚀 Deployment

🏭 Production Deployment

# Build for production
npm run build

# Start production server
NODE_ENV=production npm start

# With PM2
pm2 start server.js --name aerodrome-mcp

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

🔑 Environment Variables

# Required for transactions
WALLET_PRIVATE_KEY=your_private_key_without_0x

# Optional
PORT=8080
BASE_RPC_URL=https://mainnet.base.org
NODE_ENV=production

---

📈 Performance

• Response Time: <100ms for read operations
• Transaction Speed: ~2s on Base network
• Throughput: 100+ requests per second
• Gas Optimization: Ultra-low fees on Base
• Caching: Optimized for repeated queries

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

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

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

# Make changes and test
npm test

# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request

---

📄 License

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

---

🙏 Acknowledgments

• Aerodrome Finance - Leading DEX on Base
• Base - Ethereum L2 built by Coinbase
• Model Context Protocol - AI integration standard
• Ethers.js - Ethereum library

---

<div align="center">

Built by Tairon.ai team with help from Claude

</div>