Ethereum MCP Server

A Model Context Protocol (MCP) server implementation in Rust for Ethereum blockchain operations. This server enables AI agents to query balances, fetch token prices from Chainlink oracles, and simulate token swaps on Uniswap V2.

Supports both stdio (MCP standard) and HTTP (REST API) modes for flexible integration.

Features

MCP Tools

1. get_balance - Query ETH and ERC20 token balances

   • Supports both native ETH and any ERC20 token
   • Returns formatted balances with proper decimals
   • Concurrent fetching of token metadata

2. get_token_price - Get current token prices from Chainlink price feeds

   • Fetches real-time USD prices from Chainlink oracles
   • Calculates ETH-denominated prices
   • Includes data staleness checks
   • Cached with moka (60s TTL by default)

3. swap_tokens - Simulate token swaps on Uniswap V2

   • Constructs real Uniswap V2 transactions
   • Simulates execution using eth_call (no on-chain execution)
   • Calculates price impact and slippage protection
   • Estimates gas costs

Architecture

Technology Stack

• Rust with async/await (tokio runtime)
• ethers-rs - Ethereum RPC client and contract bindings
• axum + tower - HTTP server framework (for HTTP mode)
• moka - In-memory async cache (can be replaced with Redis for distributed deployment)
• tracing - Structured logging
• serde - Serialization/deserialization
• rust_decimal - Financial precision calculations
• clap - Command-line argument parsing

Directory Structure

ethereum-mcp-server/
├── src/
│   ├── main.rs              # Entry point, mode selection, tokio runtime
│   ├── lib.rs               # Library root
│   ├── config.rs            # Configuration management
│   ├── error.rs             # Unified error types
│   ├── mcp/                 # MCP protocol layer
│   │   ├── server.rs        # JSON-RPC 2.0 server (stdio mode)
│   │   ├── http_server.rs   # HTTP JSON-RPC server (HTTP mode)
│   │   ├── handler.rs       # Tool call routing
│   │   └── schema.rs        # Protocol schemas
│   ├── services/            # Business logic layer
│   │   ├── balance.rs       # Balance query service
│   │   ├── price.rs         # Price query service (Chainlink)
│   │   └── swap.rs          # Swap simulation service
│   ├── providers/           # External provider layer
│   │   ├── ethereum.rs      # Ethereum RPC client
│   │   ├── chainlink.rs     # Chainlink oracle with moka cache
│   │   └── uniswap.rs       # Uniswap V2 interaction
│   ├── contracts/           # Smart contract ABIs
│   │   ├── erc20.rs
│   │   ├── chainlink_feed.rs
│   │   └── uniswap_router.rs
│   └── utils/               # Utilities
│       ├── decimal.rs       # Precision handling
│       ├── validation.rs    # Input validation
│       └── wallet.rs        # Wallet management
└── tests/
    └── integration/         # Integration tests

Setup

Prerequisites

• Rust 1.70+ (install from https://rustup.rs)
• Ethereum RPC endpoint (Infura, Alchemy, or public endpoint)

Installation

1. Clone the repository:

git clone <repository-url>
cd ethereum-mcp-server

2. Copy environment configuration:

cp .env.example .env

3. Edit .env with your configuration:

# Required
RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
PRIVATE_KEY=0x0000000000000000000000000000000000000000000000000000000000000001

# Optional
LOG_LEVEL=info
PRICE_CACHE_TTL_SECS=60
CACHE_MAX_CAPACITY=1000

⚠️ Security Warning: Never commit your .env file with real private keys!

4. Build the project:

cargo build --release

Running

The server supports two modes:

1. stdio Mode (Default - MCP Standard)

cargo run --release

The server communicates via stdin/stdout using JSON-RPC 2.0 protocol.

📝 Note: When sending requests via command line, JSON must be on a single line. See [JSON_FORMAT_GUIDE.md](JSON_FORMAT_GU

... View full README on GitHub