Ethereum MCP Server
A Model Context Protocol (MCP) server built in Rust that enables AI agents to query balances and execute token swaps on Ethereum.
Features
- Query Balances: Get ETH or ERC-20 token balances for any Ethereum address
- Token Prices: Fetch current token prices from CoinGecko API
- Build Swap Transactions: Generate and simulate swap transactions using Uniswap V3
- JSON-RPC Protocol: Full MCP protocol implementation via stdin/stdout
Prerequisites
- Rust 1.70 or later - Install from rustup.rs
- Node.js 16+ (optional) - Only needed for
mcp-inspectortesting tool - Access to an Ethereum RPC endpoint - Defaults to public RPC at
https://eth.llamarpc.com
Installation
# Clone the repository
git clone <your-repo-url>
cd ethereum-mcp
# Install Rust dependencies
cargo build --release
# (Optional) Install MCP Inspector for testing
npm install
Configuration
Environment Variables
Create a .env file in the project root or export these environment variables:
# Ethereum RPC endpoint (optional, defaults to public RPC)
export ETH_RPC_URL=https://your-rpc-endpoint.com
# Private key for signing transactions (optional, required for building swap transactions)
export ETHEREUM_PRIVATE_KEY=0x1234567890abcdef...
# For mainnet, consider using Infura, Alchemy, or your own node
export ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
Security Note: Never commit private keys or .env files to version control.
Usage
Run the MCP Server
# Development mode (with logging)
cargo run
# Release mode (optimized)
cargo run --release
The server communicates via JSON-RPC over stdin/stdout, following the Model Context Protocol specification.
Test with MCP Inspector
# Start the server for inspection
mcp-inspector --transport stdio -- cargo run --release
Integration with AI Clients
Configure your AI client (e.g., Claude Desktop, Cline) to use this server:
{
"mcpServers": {
"ethereum": {
"command": "cargo",
"args": ["run", "--release"],
"cwd": "/path/to/ethereum-mcp"
}
}
}
Example MCP Tool Call
Here's an example of a complete MCP request/response interaction:
Request (from AI client to server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "query_balance",
"arguments": {
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
},
"id": 1
}
Response (from server to AI client)
{
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "ERC-20 balance: 1000000 tokens"
}
],
"isError": false
},
"id": 1
}
Available Tools
1. query_balance
Query the balance of ETH or ERC-20 tokens for an Ethereum address.
Parameters:
address(required): Ethereum address to querytoken_address(optional): ERC-20 token address. If not provided, returns ETH balance
Example:
{
"name": "query_balance",
"arguments": {
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}
}
2. get_token_price
Fetch current token price from CoinGecko API.
Parameters:
token(required): Token address, symbol (e.g., "ETH", "USDC"), or CoinGecko IDcurrency(optional): Currency to return price in (defaults to "USD")
Example:
{
"name": "get_token_price",
"arguments": {
"token": "ETH",
"currency": "USD"
}
}
3. build_swap_transaction
Build and simulate a token swap transaction using Uniswap V3.
Parameters:
fromToken(optional): Address of token to swap from (defaults to WETH)toToken(optional): Address of token to swap to (defaults to USDC)amountIn(optional): Amount to swap (defaults to 0.0001)slippageTolerance(optional): Maximum acceptable slippage percentagerecipient(optional): Address to receive swapped tokens
Example:
{
"name": "build_swap_transaction",
"arguments": {
"fromToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"toToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"amountIn": "0.1",
"slippageTolerance": 0.5
}
}
Architecture & Design Decisions
The server is organized into the following modules:
src/lib.rs: Main library entry point and server initializationsrc/mcp.rs: MCP protocol implementation and JSON-RPC handlingsrc/types.rs: Protocol type definitionssrc/ethereum/: Ethereum interaction logic organized into sub-modules:mod.rs: MainEthereumServicestruct and public APIbalance.rs: ETH and ERC-20 balance queriesprice.rs: Token price fetching from external APIspool.rs: Uniswap V3 pool operations and price calculationsswap.rs: Swap transaction building and simulationutils.rs: Helper utilities for encoding/decoding
src/main.rs: Application entry point with logging setup
Design Decisions
This implementation prioritizes safety, modularity, and type-safety through the following design choices:
-
Alloy Framework: Uses the Alloy library for Ethereum interactions, providing type-safe abstractions over raw RPC calls and eliminating common encoding/decoding errors in smart contract interactions.
-
Simulation-First Approach: All swap transactions use
eth_callfor simulation rather than executing real transactions. This allows AI agents to understand transaction outcomes without risking funds or requiring complex signing infrastructure. -
Uniswap V3 Focus: Targets Uniswap V3 specifically for its widespread adoption and concentrated liquidity. The implementation reads pool state directly from the blockchain to calculate accurate swap quotes rather than relying on external APIs.
-
Read-Only Default Mode: By default, the server operates in read-only mode. Transaction building requires explicit configuration of
ETHEREUM_PRIVATE_KEY, forcing conscious opt-in to features that could modify blockchain state. -
Rust-Based MCP Implementation: The
rmcpcrate provides a strong foundation for MCP protocol handling, with built-in async support and proper error handling, making the server more robust than ad-hoc JSON-RPC implementations.
Known Limitations & Assumptions
This implementation has the following limitations and assumptions:
-
Single Fee Tier: Only supports Uniswap V3's 0.05% fee tier (500). Other fee tiers (0.01%, 0.3%, 1%) are not automatically tried, which may miss better liquidity in alternative pools.
-
No Router Aggregation: Quotes are calculated directly from Uniswap V3 pools without considering alternative paths or aggregators (1inch, Paraswap, etc.), which may not provide optimal swap routes.
-
Simulation Only: Transactions are simulated but not executed on-chain. Actual transaction submission would require additional signing and broadcasting logic beyond the scope of this MCP server.
-
Price Oracle Dependency: Token prices come from CoinGecko's free API, which has rate limits and may not reflect real-time DEX prices. This is acceptable for approximate values but should not be used for precise arbitrage calculations.
-
Mainnet Only: Hardcoded for Ethereum mainnet addresses (Uniswap V3 contracts, token addresses). Supporting testnets or layer 2s would require additional configuration and contract addresses.
-
Token Balance Display: ERC-20 balances are returned as raw token units without decimal formatting, making large numbers hard to interpret without additional client-side processing.
-
Pool Availability Required: Input token and output token addresses must have an existing Uniswap V3 pool at the selected fee tier; otherwise the swap will not execute.
-
Approvals and Balance for Simulation: Because no transaction is sent, simulations can still fail if the user's account is not approved for the router or lacks sufficient token balance.
-
Pool-Dependent Price Calculation: Current price calculations depend on querying the pool address on-chain; this increases latency and can make simulations slower than using cached pricing services.
-
Unknown bugs: Project is not fully tested, unknown behavior might happen.
Development
Run tests:
cargo test
Format code:
cargo fmt
Run linter:
cargo clippy
Security Considerations
⚠️ Important: This is an experimental MCP server for Ethereum blockchain interactions:
-
Environment Variables: Never commit
.envfiles or private keys to version control. Use secure key management in production. -
Private Key Storage: The
ETHEREUM_PRIVATE_KEYenvironment variable is loaded directly. For production, consider using hardware wallets or secure key management services (AWS KMS, GCP Secret Manager, etc.). -
Read-Only Mode: The server defaults to read-only mode for safety. Building transactions requires explicit configuration.
-
Rate Limiting: Public RPC endpoints have rate limits. Use dedicated RPC providers (Infura, Alchemy) for production workloads.
-
Transaction Simulation: All swaps are simulated only. No actual transactions are executed unless you build custom broadcasting logic.
-
Input Validation: All user inputs are validated, but additional checks may be needed for production use.
License
[Add your license here]
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.