ustclhx/eth-trading-mcp

Ethereum Trading MCP Server

A Model Context Protocol (MCP) server written in Rust, enabling AI agents or CLI clients to:

• Query ETH & ERC20 balances
• Fetch token prices (ETH or USD)
• Simulate Uniswap V3 swaps (read-only via QuoterV2)

The server communicates over JSON-RPC 2.0 (stdin/stdout) and can connect to any Ethereum RPC endpoint such as Infura, Alchemy, or a local anvil fork.

Setup Instructions

1. Dependencies

You'll need:

• Rust toolchain ≥ 1.73 (rustup recommended)
• cargo build system (installed with Rust)
• Access to an Ethereum RPC node (Infura, Alchemy, or a local fork)

2. Environment Variables (.env)

Create a .env file in the project root based on the .env.example file

If you don't have a public RPC key, you can use a local fork:

anvil --fork-url https://eth.llamarpc.com --chain-id 1 --port 8545

3. Running the MCP Server

cargo run --quiet

The server reads JSON-RPC requests from stdin and writes responses to stdout.

To test manually, use jq:

jq -nc '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | cargo run --quiet

Example MCP Tool Calls

1️⃣ List available tools

Request

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Response

{ "jsonrpc":"2.0", "id":1, "result":{ "tools":[ {"name":"get_balance","description":"Query ETH or ERC20 balance"}, {"name":"get_token_price","description":"Fetch token price in ETH or USD"}, {"name":"swap_tokens","description":"Simulate Uniswap V3 single-hop swap"} ] } }

2️⃣ Query ETH balance for a specific address

Request

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_balance", "arguments": { "address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" } } }

Response

{ "jsonrpc": "2.0", "id": 2, "result": { "Ok": { "symbol": "ETH", "decimals": 18, "amount": "9999.999999999" } } }

3️⃣ Get token price (ETH per USDC)

Request

{ "jsonrpc":"2.0", "id":3, "method":"tools/call", "params":{ "name":"get_token_price", "arguments":{ "token":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "vs":"ETH", "fee":3000 } } }

Response

{ "jsonrpc":"2.0", "id":3, "result":{ "Ok":{ "token":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "vs":"ETH", "price":"0.00029" } } }

4️⃣ Simulate Uniswap V3 Swap (ETH → USDC)

Request

{ "jsonrpc":"2.0", "id":4, "method":"tools/call", "params":{ "name":"swap_tokens", "arguments":{ "from_token":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "to_token":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "amount":"10000000000000000", "slippage_bps":50, "use_v3":true, "v3_fee":3000 } } }

Response

{ "jsonrpc":"2.0", "id":4, "result":{ "Ok":{ "router":"UniswapV3/QuoterV2", "method":"quoteExactInput(bytes)", "estimated_output":"34021798", "gas_estimate":0, "gas_price_wei":"18000000000", "route_hint":"0xc02a...->(3000)->0xa0b8..." } } }

Design Decisions

MCP stdio architecture: The server follows the Model Context Protocol spec, exposing tools via tools/list and tools/call on stdin/stdout. This design avoids network binding and integrates easily into AI agent runtimes.

Ethereum RPC abstraction: All on-chain reads use ethers-rs with async I/O. The server supports both public RPC endpoints (Infura/Alchemy) and local forks via anvil.

Composable modules:

eth.rs — core balance utilities

price.rs — Uniswap V3 + Chainlink pricing

uniswap.rs — swap simulation via QuoterV2

mcp.rs — unified JSON-RPC tool dispatcher

types.rs — shared request/response schemas

Precision handling: Uses rust_decimal and BigDecimal internally for safe financial math across token pairs with differing decimals.

Known Limitations & Assumptions

Simulation only: swaps are never broadcast on-chain.

ETH/USD pricing assumes the Chainlink mainnet aggregator at address 0x5f4e...b8419.

decimals() handling may fail for non-standard ERC20s unless you use the provided safe_erc20_decimals.

RPC endpoints must allow eth_call, eth_getCode, and eth_gasPrice.

The server does not maintain state or wallet keys; it is read-only.

Quick Test

Test Functionality Overview

The test script test_mcp_client.py verifies the core functionalities of the MCP (Market Connect Platform) service, including:

• Querying the list of available tools
• Getting ETH balance for Ethereum addresses
• Getting token balances (e.g., USDC) for Ethereum addresses
• Retrieving token price information relative to ETH
• Simulating token swap operations (from WETH to USDC)

Prerequisites

Before running the tests, ensure that:

1. You have created and configured the .env file
2. You have an available Ethereum RPC node locally (such as an anvil node)
3. Python 3 environment is installed

Running Tests

Basic Test (Using Default Configuration)

cd test
python3 test_mcp_client.py

This will start the service using the default cargo command and connect to the default RPC node (http://127.0.0.1:8545).

Custom Test Parameters

You can customize the test configuration through command-line parameters:

# Specify a different RPC node
python3 test_mcp_client.py --rpc https://eth.llamarpc.com

# Specify the wallet address to test
python3 test_mcp_client.py --addr 0xYourWalletAddress

# Specify different WETH and USDC contract addresses
python3 test_mcp_client.py --weth 0xYourWETHAddress --usdc 0xYourUSDCAddress

# Specify a custom server start command
python3 test_mcp_client.py --server-cmd "cargo" "run" "--release"

Environment Variables

The test script automatically reads configuration from environment variables, particularly:

• ETH_RPC_URL: Ethereum RPC node URL (if not specified via command-line parameter)

Test Results

When tests pass successfully, you will see output similar to:

✓ tools/list OK
✓ get_balance(ETH) OK
✓ get_balance(USDC) OK
✓ get_token_price(vs=ETH) OK
✓ swap_tokens (simulate) OK

ALL TESTS PASSED ✅

If tests fail, detailed error information and server logs will be displayed for debugging.

Note: Token swap functionality currently only performs simulation operations and will not execute actual on-chain transactions.