eth-trading-mcp-server

ytwei3/eth-trading-mcp-server

3.2

If you are the rightful owner of eth-trading-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Ethereum Trading MCP Server is a Rust-based implementation that allows AI agents to interact with Ethereum for balance queries, price feeds, and swap simulations using natural language.

Tools
3
Resources
0
Prompts
0

Ethereum Trading MCP Server

A Model Context Protocol (MCP) server implementation in Rust that enables AI agents to query balances and simulate token swaps on Ethereum.

Quick Start for AI Agents

This server allows AI agents like Claude to interact with Ethereum through natural conversation:

  1. Build: cargo build --release
  2. Configure Claude Desktop (see Configuring with AI Agents)
  3. Chat with Claude: "What's the ETH balance of vitalik.eth?"

That's it! The AI will call the blockchain tools automatically.

Features

  • Balance Queries: Query ETH and ERC20 token balances for any address
  • Price Feeds: Get real-time token prices from CoinGecko and Chainlink oracles
  • Swap Simulation: Simulate Uniswap V2 swaps with gas estimation (no on-chain execution)
  • MCP Protocol: Full JSON-RPC 2.0 implementation following MCP specification
  • Production-Ready: Uses ethers-rs for Ethereum interactions, rust_decimal for financial precision

Prerequisites

  • Rust 1.70 or higher
  • An Ethereum RPC endpoint (public or from Infura/Alchemy)

Installation

  1. Clone the repository:
git clone <repository-url>
cd eth-trading-mcp-server
  1. Copy the example environment file:
cp .env.example .env
  1. Edit .env and configure your Ethereum RPC URL:
ETH_RPC_URL=https://eth.llamarpc.com
# Or use your own Infura/Alchemy endpoint:
# ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_API_KEY
  1. Build the project:
cargo build --release

Running the Server

The MCP server communicates via stdio (standard input/output):

cargo run --release

The server will:

  1. Connect to the Ethereum RPC endpoint
  2. Verify the connection by fetching the chain ID
  3. Listen for JSON-RPC requests on stdin
  4. Send responses on stdout

Configuring with AI Agents

This MCP server is designed to be used by AI agents like Claude Desktop, which can call the Ethereum tools through natural conversation.

Option 1: Claude Desktop (Recommended)

  1. Build the release binary:

    cargo build --release

  2. Locate the binary:

    # The binary will be at:
# /Users/hikari/src/eth-trading-mcp-server/target/release/eth-trading-mcp-server

  3. Configure Claude Desktop:

    Edit your Claude Desktop config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

    Add this MCP server configuration:

    {
  "mcpServers": {
    "ethereum-trading": {
      "command": "/Users/hikari/src/eth-trading-mcp-server/target/release/eth-trading-mcp-server",
      "env": {
        "ETH_RPC_URL": "https://eth.llamarpc.com"
      }
    }
  }
}

    Note: Replace the path with your actual project path. Use pwd in the project directory to get the full path.

  4. Restart Claude Desktop

  5. Verify installation: Open Claude Desktop and look for the 🔌 icon indicating MCP servers are connected.

Option 2: Other MCP Clients

For other MCP-compatible clients, configure them to run:

/path/to/eth-trading-mcp-server/target/release/eth-trading-mcp-server

With environment variable:

ETH_RPC_URL=https://eth.llamarpc.com

Testing with Natural Language

Once configured with Claude Desktop, you can test the tools by chatting naturally:

Balance Queries:

  • "What's the ETH balance of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?"
  • "Check the USDC balance for vitalik.eth"
  • "How much ETH does 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb have?"

Price Queries:

  • "What's the current price of USDC?" (then provide address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48)
  • "Get me the ETH price" (use 0x0000000000000000000000000000000000000000)
  • "What's the price of token 0x6B175474E89094C44Da98b954EedeAC495271d0F?" (DAI)

Swap Simulations:

  • "Simulate swapping 0.1 ETH to USDC for wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  • "How much USDC would I get for 1 ETH?"
  • "Show me the gas cost for swapping 0.5 ETH to DAI"

Common Token Addresses:

  • ETH: 0x0000000000000000000000000000000000000000
  • USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
  • USDT: 0xdAC17F958D2ee523a2206206994597C13D831ec7
  • DAI: 0x6B175474E89094C44Da98b954EedeAC495271d0F
  • WETH: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

The AI agent (Claude) will:

  1. Understand your natural language request
  2. Call the appropriate MCP tool (get_balance, get_token_price, or swap_tokens)
  3. Present the results in a human-friendly format

Available Tools

1. get_balance

Query ETH or ERC20 token balance for a wallet address.

Parameters:

  • wallet_address (string, required): The wallet address to query (0x...)
  • token_address (string, optional): ERC20 token contract address. If not provided, returns ETH balance.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {
      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Balance: 1.234567890123456789 ETH\nDecimals: 18\nWallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\nRaw balance: 1234567890123456789"
      }
    ]
  }
}

2. get_token_price

Get current token price in USD and ETH from price oracles.

Parameters:

  • token_address (string, required): Token contract address. Use 0x0000000000000000000000000000000000000000 for ETH.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_token_price",
    "arguments": {
      "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Token: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\nPrice (USD): 1.00\nPrice (ETH): 0.0005\nSource: CoinGecko"
      }
    ]
  }
}

3. swap_tokens

Simulate a token swap on Uniswap V2 without executing the transaction.

Parameters:

  • from_token (string, required): Source token address. Use 0x0000000000000000000000000000000000000000 for ETH.
  • to_token (string, required): Destination token address
  • amount (string, required): Amount to swap in token units (e.g., "1.5")
  • slippage_bps (number, optional): Slippage tolerance in basis points (default: 50 = 0.5%)
  • wallet_address (string, required): Wallet address for simulation

Example Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "swap_tokens",
    "arguments": {
      "from_token": "0x0000000000000000000000000000000000000000",
      "to_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "amount": "1.0",
      "slippage_bps": 50,
      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Swap Simulation:\nFrom: 0x0000000000000000000000000000000000000000\nTo: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\nAmount In: 1.0\nEstimated Output: 2000.5\nMinimum Output (with slippage): 1990.4975\nEstimated Gas: 150000\nSlippage Tolerance: 50 bps (0.5%)\nRoute: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 -> 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
      }
    ]
  }
}

MCP Protocol Flow

  1. Initialize: Client sends initialize request
  2. List Tools: Client requests available tools with tools/list
  3. Call Tool: Client invokes tools with tools/call

Example initialization:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Design Decisions

Architecture

  1. Modular Design: Separated concerns into distinct modules (ethereum/, tools/, types.rs, mcp.rs) for maintainability and testability.

  2. Async-First: Built on Tokio for efficient handling of concurrent RPC calls and future scalability.

  3. Simulation Only: The swap_tokens tool uses eth_estimateGas and getAmountsOut to simulate swaps without executing transactions, ensuring safety for AI agents.

  4. Financial Precision: Uses rust_decimal throughout to avoid floating-point errors in financial calculations.

  5. Price Oracle Strategy: Implements a fallback chain (CoinGecko → Chainlink → Uniswap pools) to maximize price data availability.

Implementation Details

  • Uniswap Integration: Uses Uniswap V2 Router for swap simulations due to its simplicity and widespread adoption
  • ABI Generation: Leverages ethers-rs abigen! macro for type-safe contract interactions
  • Error Handling: Comprehensive error handling with anyhow for internal errors and JSON-RPC error codes for client responses
  • Logging: Structured logging with tracing, output to stderr to avoid interfering with stdio protocol

Known Limitations

  1. Mainnet Only: Currently configured for Ethereum mainnet. Would need modifications for L2s or testnets.

  2. Price Feeds: CoinGecko API has rate limits. For production, implement caching or use paid API tiers.

  3. Swap Routing: Uses simple direct paths (token A → token B) or single-hop through WETH. Production systems should implement multi-hop routing for better prices.

  4. Gas Estimation: May be inaccurate for complex scenarios. The eth_estimateGas call can fail if the wallet lacks sufficient balance.

  5. No Transaction Execution: This server only simulates swaps. To execute real transactions, you'd need to:

    • Add proper wallet management with secure key storage
    • Implement transaction signing and broadcasting
    • Add confirmation tracking
    • Handle nonce management

  6. Uniswap V2 Only: Does not support Uniswap V3 or other DEXs. V3's concentrated liquidity would provide better pricing but requires more complex integration.

Testing

Recommended: Test with AI Agent

The best way to test this server is through an AI agent like Claude Desktop (see Configuring with AI Agents above). Simply chat with Claude using natural language like:

  • "What's the ETH balance of vitalik.eth?"
  • "Get the price of USDC"
  • "Simulate swapping 1 ETH to USDC"

Alternative: Manual Testing

If you want to test the server directly without an AI agent:

Python Test Client

A Python test client (client_example.py) is provided for easy end-to-end testing of all MCP server functionality:

# Make the script executable
chmod +x client_example.py

# Initialize the server
python3 client_example.py init

# List available tools
python3 client_example.py list

# Test balance query (example: Vitalik's address)
python3 client_example.py balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Test token price (example: USDC)
python3 client_example.py price 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

# Test swap simulation (ETH -> USDC)
python3 client_example.py swap 0x0000000000000000000000000000000000000000 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 0.1 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Available commands:

  • init - Initialize the MCP server connection
  • list - List all available tools
  • balance <wallet_address> - Query wallet balance
  • price <token_address> - Get token price (use 0x0000000000000000000000000000000000000000 for ETH)
  • swap <from_token> <to_token> <amount> <wallet_address> - Simulate token swap

Bash Test Script

A simple bash script (test_mcp.sh) is also provided for quick testing:

chmod +x test_mcp.sh
./test_mcp.sh

This script displays example JSON-RPC requests that can be sent to the server.

Rust Tests

Run the test suite:

cargo test

Run with logging:

RUST_LOG=debug cargo test -- --nocapture

Development

Enable debug logging:

RUST_LOG=debug cargo run

Format code:

cargo fmt

Run linter:

cargo clippy

Security Considerations

  • Never commit .env files containing private keys
  • This server simulates transactions only - no private keys are required for basic operation
  • For production use, implement proper secret management (e.g., HashiCorp Vault, AWS Secrets Manager)
  • Always validate and sanitize inputs, especially addresses and amounts

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.