liyorozuya/crypto-mcp-server

Crypto MCP Server

Rust-based Model Context Protocol (MCP) server that lets AI agents inspect Ethereum balances, quote token prices, and build simulated Uniswap swaps without broadcasting on-chain transactions.

Prerequisites

System Requirements

• Rust toolchain: 1.78+ (recommended: latest stable)
• Operating System: Linux, macOS, or Windows
• Network: Access to an Ethereum RPC endpoint (HTTPS)
• Memory: Minimum 512MB RAM (recommended: 1GB+)
• Disk Space: ~500MB for Rust toolchain + dependencies

Installing Rust

If you don't have Rust installed:

# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version
cargo --version

Configuration

Configuration can be provided via environment variables (priority) or config file (config.toml).

Option 1: Environment Variables (Recommended)

Set the following environment variables:

Example:

export ETH_RPC_URL="https://eth.llamarpc.com"
export CHAIN_ID=1
export DEFAULT_SLIPPAGE_BPS=50

Option 2: Config File

If environment variables are not set, the application will read from config.toml:

[ethereum]
rpc_url = "https://eth.llamarpc.com"
chain_id = 1
default_slippage_bps = 50
wallet_private_key = ""  # Optional

Copy config.toml.example to config.toml and customize it:

cp config.toml.example config.toml

Public RPC Endpoints

Free public RPC endpoints (may have rate limits):

• https://eth.llamarpc.com
• https://cloudflare-eth.com
• https://rpc.ankr.com/eth
• https://ethereum.publicnode.com

For production, consider using:

• Infura: https://mainnet.infura.io/v3/YOUR_PROJECT_ID
• Alchemy: https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
• QuickNode: https://YOUR_ENDPOINT.quiknode.pro/YOUR_API_KEY/

See for more details.

Security note: the private key is only used locally for the from field when simulating swaps (eth_call/estimateGas). No signed transactions are broadcast. Never commit config.toml with real private keys to version control.

Building

Development Build

# Clone the repository (if not already done)
git clone <repository-url>
cd crypto

# Build in debug mode (faster compilation, slower runtime)
cargo build

# Run directly
cargo run

Release Build (Recommended for Production)

# Build optimized release binary
cargo build --release

# Binary will be located at: target/release/crypto_mcp
# Size: ~8.5MB (statically linked, no external dependencies required)

# Run the release binary
./target/release/crypto_mcp

Build Notes:

• Release builds are optimized for performance and smaller binary size
• Compilation warnings (unused code) don't affect functionality
• The binary is statically linked and can run on systems without Rust installed
• Build time: ~30-60 seconds (first build), ~5-10 seconds (incremental)

Cross-Compilation

To build for different platforms:

# Install cross-compilation target
rustup target add x86_64-unknown-linux-musl  # Linux
rustup target add x86_64-apple-darwin        # macOS
rustup target add x86_64-pc-windows-gnu      # Windows

# Build for specific target
cargo build --release --target x86_64-unknown-linux-musl

Running

Quick Start

# Set environment variables
export ETH_RPC_URL="https://eth.llamarpc.com"
export CHAIN_ID=1

# Run (development)
cargo run

# Or run release binary
./target/release/crypto_mcp

The server communicates over MCP stdio transport. Connect using an MCP-compatible client and invoke one of the tools:

• get_server_info
• get_balance
• get_token_price
• swap_tokens

get_server_info is a lightweight health endpoint that shares the chain ID, configured slippage default, whether a wallet is loaded (required for swap simulations), and the supported swap protocols.

Example MCP Tool Call

Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
    }
  }
}

Response (truncated):

{
  "content": [
    {
      "type": "json",
      "data": {
        "balances": [
          {
            "token": {
              "address": "0x0000000000000000000000000000000000000000",
              "symbol": "ETH",
              "decimals": 18,
              "isNative": true
            },
            "rawBalance": "1234567890000000000",
            "normalizedBalance": "1.23456789"
          }
        ]
      }
    }
  ]
}

swap_tokens responses now include live gas diagnostics:

• gasPrice: current network gas price (ETH)
• estimatedGas: router gas limit estimate (wei)
• estimatedFeeNative: gasPrice * estimatedGas, expressed in ETH

Deployment

Quick Deployment Script

Use the provided deployment script for automated setup:

# Make script executable
chmod +x scripts/deploy.sh

# Run deployment (interactive)
./scripts/deploy.sh

# Or with environment variables
ETH_RPC_URL="https://eth.llamarpc.com" ./scripts/deploy.sh

The script will:

1. Check Rust installation
2. Build release binary
3. Create deployment directory
4. Copy binary and configuration files
5. Set up systemd service (Linux) or launchd plist (macOS)

Manual Deployment

1. Build the release binary:

   cargo build --release
   

2. Create deployment directory:

   mkdir -p /opt/crypto-mcp
   cp target/release/crypto_mcp /opt/crypto-mcp/
   cp config.toml.example /opt/crypto-mcp/config.toml
   

3. Configure:

   # Edit config.toml or set environment variables
   nano /opt/crypto-mcp/config.toml
   

4. Run as service:

   • Linux (systemd): See scripts/crypto-mcp.service
   • macOS (launchd): See scripts/com.crypto-mcp.plist

Docker Deployment (Optional)

# Build Docker image
docker build -t crypto-mcp:latest .

# Run container
docker run -d \
  --name crypto-mcp \
  -e ETH_RPC_URL="https://eth.llamarpc.com" \
  -e CHAIN_ID=1 \
  crypto-mcp:latest

Tests

Running Tests

# Run all tests (unit tests only, no network calls)
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_config_missing_rpc_url

# Run system tests (requires ETH_RPC_URL)
ETH_RPC_URL=https://eth.llamarpc.com cargo test -- --include-ignored

Test Coverage:

• Unit Tests: 33 tests covering deterministic logic (slippage math, routing decisions, config parsing)
• System Tests: 4 E2E tests requiring live RPC endpoint
• Unit tests are fast and isolated (no external dependencies)
• System tests validate real on-chain interactions

Design Notes

1. Async Ethereum client: ethers-rs with Tokio drives all RPC calls, providing ABI bindings for ERC-20s and Uniswap routers plus cached metadata lookups.
2. MCP integration: the rmcp SDK registers each tool with input/output schemas so clients can discover parameters automatically, and tracing logs capture tool-level events.
3. Financial precision: rust_decimal handles normalization for human-readable balances/prices while raw U256 values remain available for encoding transactions.
4. Swap simulations: swaps are quoted via Uniswap router/quoter contracts, then real transactions are constructed and submitted via eth_call/estimateGas for insight without execution.

Performance

• Startup Time: < 1 second
• Memory Usage: ~50-100MB at runtime
• Binary Size: ~8.5MB (release build)
• Response Time:
  • Balance queries: 100-500ms (depends on RPC latency)
  • Price quotes: 200-800ms
  • Swap simulations: 500ms-2s (includes gas estimation)

Known Limitations

• Swap simulations revert if the configured wallet lacks allowances; the server surfaces the revert reason in warnings but does not auto-approve tokens.
• V3 swaps currently require ERC20 tokens (wrap/unwrap ETH to WETH manually before using protocol="v3").
• Price quotes rely on Uniswap V2 liquidity (USDC/WETH routing) and treat USDC ≈ USD; no fallback to other DEXes or Chainlink feeds is implemented.
• Tests avoid live RPC calls, so contract/address regressions must be validated manually against mainnet.
• Compilation warnings: Some unused code exists (DEX registry, protocol selector) - these are planned features and don't affect current functionality.

Code Flow

sequenceDiagram
    participant Client as MCP Client
    participant Server as CryptoMcpServer
    participant Context as EthereumContext
    participant RPC as Ethereum RPC

    Client->>Server: tools/call (e.g., swap_tokens)
    Server->>Context: resolve_asset / metadata cache
    Context-->>RPC: eth_call (ERC20 symbol/decimals) [cached]
    Server->>Context: quote + build transaction\n(Uniswap router/quoter)
    Context-->>RPC: eth_call / estimateGas (simulation)
    Server->>Client: Json response\n(balances, price, swap simulation)