MCP Eth Server

mcp-eth-server 翻译为中文是“MCP以太网服务器”

使用Rust构建的以太坊MCP（模型上下文协议）服务器 rmcp SDK（可流式传输-HTTP）。

特点/功能

工具

• get_balance – 查询任意地址的ETH/ERC20代币余额
• get_token_price – 通过Uniswap V3 QuoterV2获取链上代币价格（使用quoteExactInputSingle以获取准确的单池报价，基准为USDC或ETH）
• swap_tokens – 在Uniswap V3上模拟代币交换（构建真实交易并使用 eth_call - 不在链上执行）

建筑学

• McpServer - 主服务器包装器，支持多种传输方式
• EthServer - 工具路由器实现与 #[tool_router] 宏（在计算机领域，指的是一系列预定义的命令或指令集，用于简化重复性任务）
• 使用官方工具构建 rmcp Rust SDK（软件开发工具包）
• 使用JSON Schema生成实现类型安全的参数提取
• 支持stdio和HTTP传输方式
• 使用 Tokio 运行时的 Async/await
• 使用结构化日志记录 tracing

快速入门

先决条件

• Rust 1.90.0 或更高版本
• 以太坊RPC端点（Infura、Alchemy或本地节点）
• 用于交易模拟的私钥

设置

# Set Rust version
rustup override set 1.90.0

# Copy example config
cp config.example.yaml config.yaml

# Edit config.yaml with your settings

从水龙头获取Sepolia以太坊（ETH）：

• https://www.alchemy.com/faucets/ethereum-sepolia 的中文翻译为：“https://www.alchemy.com/faucets/以太坊塞普洛利亚（测试网）水龙头”。不过，为了更符合中文表达习惯，我们通常会将“Ethereum Sepolia”翻译为“以太坊塞普洛利亚测试网”，因此更完整的中文表述可以是：“https://www.alchemy.com/faucets/以太坊塞普洛利亚测试网水龙头”
• https://sepoliafaucet.com/ 可以翻译为：“https://sepoliafaucet.com/（塞普勒西亚水龙头网站）”。不过，通常在实际应用中，我们可能直接保留网址不变，因为网址本身就是国际通用的，无需翻译。但如果要对网址所代表的含义进行解释性翻译，上述句子是一个示例。在具体语境中，根据需要选择是否翻译网址或仅解释其含义
• https://www.infura.io/faucet/sepolia 的中文翻译可以是：“Infura.io Sepolia 测试网 faucet（注水器/领取测试代币的网站）”。不过，为了更自然地表达，我们通常会说：“Infura.io 提供的 Sepolia 测试网测试代币领取服务”或者“访问 Infura.io 的 Sepolia 测试网 faucet 以领取测试代币”

构建并运行

# Build
cargo build

# Run with default config (config.yaml)
cargo run

# Run with specific config
cargo run config.testnet.yaml
cargo run /path/to/custom-config.yaml

# Run tests
cargo test

与光标一起使用

在您的Cursor配置中添加：

{
  "mcpServers": {
    "eth-mcp-server": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

与MCP Inspector的使用

# Install MCP Inspector
npx @modelcontextprotocol/inspector

# Run server
cargo run

# Connect Inspector to Streamable HTTP transport

工具示例

示例1：获取余额

MCP 请求：

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

MCP响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Balance: 1234.567890123456 ETH"
      }
    ]
  }
}

带有代币地址（USDC）：

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

示例2：获取代币价格

MCP 请求:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_token_price",
    "arguments": {
      "token": "WETH",
      "base": "USD"
    }
  }
}

MCP响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "WETH Price: $2,450.00 USD\nSource: Uniswap V3 QuoterV2 (WETH/USDC pool)\nMethod: quoteExactInputSingle"
      }
    ]
  }
}

示例3：交换代币（模拟）

MCP 请求:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "swap_tokens",
    "arguments": {
      "from_token": "WETH",
      "to_token": "USDC",
      "amount_in": "1.0",
      "slippage_bps": 50
    }
  }
}

MCP响应：

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Swap Simulation (Uniswap V3)\n\nInput: 1.0 WETH\nExpected Output: 2,438.25 USDC\nMinimum Output: 2,426.05 USDC (0.5% slippage)\n\nFee Tier: 0.05% (500)\nPrice Impact: ~0.02%\n\nGas Estimate: 150,000 units\nEstimated Gas Cost: 0.0045 ETH (~$11.00)\n\n⚠️ SIMULATION ONLY - Transaction not executed\n✓ Token approval may be required"
      }
    ]
  }
}

测试

# Run all tests,Before running 

cp config.example.yaml config.testnet.yaml # update to your private key, and ensuer your wallet have eth on sepolia network

cargo test

设计决策

建筑设计方法

1. MCP协议合规性使用官方工具构建 rmcp Rust SDK确保与MCP规范的完全兼容性，并支持与Claude Desktop的集成

1. 分层架构：

- McpServer传输层（HTTP）管理 - EthServer工具路径规划与 #[tool_router] 宏观；大（规模/结构） - 业务逻辑：用于余额、价格和交换操作的纯函数 - 支持独立测试，便于轻松添加新工具/传输方式

1. 类型安全与自动化:

- #[tool_router] 宏自动生成工具注册和路由 - 通过（某种方式）从Rust类型派生出的JSON Schema schemars - 编译时参数验证 Parameters - 新增工具时无需任何样板代码

1. “Simulation-First Safety”可以翻译为“先模拟后安全”或“以模拟为先的安全”。这里，“Simulation-First”强调的是在进行任何实际操作或决策之前，首先通过模拟来进行验证和测试，以确保安全。因此，“以模拟为先的安全”或“先模拟后安全”都准确地传达了这一理念:

- 所有交换操作均使用 eth_call 用于模拟 - 构建真实的Uniswap V3交易，但从未广播 - 提供准确的气体估算，无需链上执行 - 使用真实私钥进行生产时安全无虞

1. 财务精准度：

- 用途 rust_decimal 用于所有代币计算 - 正确处理代币的小数位数（USDC为6位，ETH为18位） - 防止金融运算中的浮点数错误

已知的限制

当前范围

• 网络主要以太坊主网为焦点（可通过配置调整 CHAIN_ID也支持Sepolia测试网
• DEX仅限Uniswap V3，单跳兑换（计划支持多跳）
• 令牌解析内置符号支持WETH、USDC、USDT、DAI；其他代币需提供完整合约地址
• 价格预言机使用Uniswap V3的QuoterV2和quoteExactInputSingle功能，通过USDC池获取准确的链上价格

假设

• RPC 端点可靠，返回准确数据
• 私钥仅用于交易模拟（绝不广播）
• 为生产环境使用设置足够的RPC速率限制
• 代币合约遵循标准的ERC20接口

项目结构

src/
├── main.rs              # Entry point - creates McpServer
├── mcp.rs               # McpServer - handles stdio/HTTP transports
├── lib.rs               # Module definitions
├── config.rs            # Configuration management
├── types.rs             # Input/Output types with JsonSchema
├── tools/
│   ├── router.rs        # EthServer with #[tool_router]
│   ├── balance.rs       # Balance query implementation
│   ├── price.rs         # Price query via Uniswap V3 QuoterV2
│   └── swap.rs          # Swap simulation implementation
├── uniswap/             # Uniswap V2/V3 integrations

架构流程

main.rs
  └─> McpServer::new(config)
       └─> EthServer::new(config)  [has #[tool_router]]
            ├─> get_balance (tool)
            ├─> get_token_price (tool)
            └─> swap_tokens (tool)
       └─> run_http()
            └─> Uses rmcp transports