cowboy0015/ethereum-mcp-server

Ethereum MCP Server

An MCP (Model Context Protocol) server built in Rust that enables AI agents to interact with Ethereum. The server provides tools for querying balances, fetching token prices, and simulating token swaps on Uniswap V3.

Features

• Balance Queries: Get ETH and ERC-20 token balances for any Ethereum address
• Token Prices: Fetch current token prices from CoinGecko API (USD/ETH)
• Swap Simulation: Construct and simulate Uniswap V3 token swaps without executing on-chain
• MCP Protocol: Full MCP server implementation with JSON-RPC 2.0 compliance

Prerequisites

• Rust 1.75+ and Cargo
• Ethereum RPC endpoint (public or private)
• Private key for transaction signing (simulation only)
• CoinGecko API key (optional, demo key included)

Quick Start

1. Clone and Build

git clone https://github.com/cowboy0015/ethereum-mcp-server.git
cd ethereum-mcp-server
cargo build --release

2. Configure Environment Copy the example environment file and modify it:

cp .env.example .env

Edit .env with your configuration:

# Required: Your Ethereum private key (for simulation)
PRIVATE_KEY=0x45ff7f5de016d7aa75787576efe1e58c972d22169277e587d4fa46dfa995a79b
# Optional: Override defaults
ETHEREUM_RPC_URL=https://eth.llamarpc.com  # Any Ethereum RPC endpoint. Check https://chainlist.org/ if you want to use public rpc endpoint
UNISWAP_V3_ROUTER=0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45
UNISWAP_V3_FACTORY=0x1F98431c8aD98523631AE4a59f267346ea31F984

3. Run the Server

cargo run --release

The server will start and communicate via stdin/stdout using the MCP protocol.

MCP Tool Examples

Get Balance

• Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
  }
}

• Response:

{
    "content": [
        {
            "type": "text",
            "text": "ERC20 balance: Token balance: 38826263261"
        }
    ],
    "isError": false
}

Get Token Price

• Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_token_price",
    "arguments": {
      "currency": "usd",
      "token": "eth"
    }
  }
}

• Response:

{
    "content": [
        {
            "type": "text",
            "text": "ETH: 3063.63 USD"
        }
    ],
    "isError": false
}

Swap Tokens (Simulation)

• Request:

{
  "method": "tools/call",
  "params": {
    "name": "swap_tokens",
    "arguments": {
      "amountIn": "100",
      "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "slippageTolerance": 0.5,
      "toToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
    }
  }
}

• Response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Swap Simulation:\nFrom: 100 USDC\nTo: 0.0321 WETH\nMin Out (0.5% slippage): 0.0319 WETH\nEstimated Gas: 150000 wei\nSimulation successful - transaction would succeed"
    }]
  }
}

Design Decisions

1. Modular Architecture: The code is organized into focused modules (swap.rs, pool.rs, balance.rs, price.rs) for clear separation of concerns and easier testing.

2. Simulation-First Swaps: Instead of executing transactions, we construct real Uniswap V3 transactions and simulate them using eth_call, providing accurate gas estimates and success/failure feedback without spending real ETH.

3. Decimal Precision: Uses rust_decimal for all financial calculations to avoid floating-point precision issues, ensuring accurate swap calculations and balance queries.

4. Provider Abstraction: Leverages Alloy's provider system for Ethereum interactions, making it easy to switch between different RPC providers or networks.

5. Error Resilience: Comprehensive error handling with fallback mechanisms (e.g., if pool price calculation fails, falls back to quote-based estimation).

Known Limitations & Assumptions

1. Uniswap V3 Only: Currently only supports Uniswap V3 swaps. V2 pools are not supported but could be added with minimal changes.

2. Fixed Fee Tier: Uses only the 0.05% fee tier (500 bps). In production, you'd want to check multiple fee tiers or let users specify.

3. Price Source: Token prices come from CoinGecko's public API with rate limits. For production use, you'd need your own API key and potentially multiple price sources.

4. Single Slippage Model: Uses a simple percentage-based slippage calculation. More sophisticated models (TWAP, dynamic slippage) would be needed for large swaps.

5. Static Configuration: Private keys and RPC URLs are loaded from environment variables at startup. For a production system, you'd want dynamic wallet management.

6. Simulation Only: The server only simulates swaps. Actual transaction signing and broadcasting would require additional integration with a wallet provider.

Testing

Run the test suite:

cargo test

Tests include:

• Balance query validation
• Swap parameter validation
• Price fetching
• Unit tests for utility functions

Logging

Logs are written to logs/ethereum.log with daily rotation. The logging level is set to INFO by default. Logs include:

• Tool invocation details
• Ethereum RPC calls
• Simulation results
• Error conditions

Security Considerations

Important: This server uses a private key for transaction simulation but never broadcasts transactions. However:

1. Never use a private key with real funds in development
2. The private key should be for a test purpose only
3. All RPC calls are read-only (eth_call, eth_getBalance)
4. No transaction signing or broadcasting occurs

Dependencies

Key dependencies:

• alloy: Ethereum RPC client and ABI handling
• rmcp: MCP protocol implementation
• rust_decimal: Precise decimal arithmetic
• tracing: Structured logging
• reqwest: HTTP client for price API
• dotenv: Environment variable management