EVM MCP Server

EVM MCP 服务

一个功能全面的模型上下文协议（MCP）服务，为多个兼容 EVM 的网络提供区块链服务。该服务通过统一的接口，让 AI Agent 能够与 Ethereum、Optimism、Arbitrum、Base、Polygon 以及许多其他 EVM 链交互。

📋 目录

• 概述
• 功能
• 支持的网络
• 先决条件
• 安装
• 服务配置
• 用法
• API 参考
  • 工具
  • 资源
• 安全注意事项
• 项目结构
• 开发
• 许可证

🔭 概述

MCP EVM 服务利用模型上下文协议向 AI Agent 提供区块链服务。它支持多种服务，包括：

• 读取区块链状态（余额、交易、区块等）
• 与智能合约交互
• 转移代币（原生代币、ERC20、ERC721、ERC1155）
• 查询代币元数据和余额
• 为 30 多个 EVM 网络提供链专属服务
• ENS 名称解析，适用于所有地址参数（使用 vitalik.eth 等易读名称代替地址）

所有服务都通过统一的 MCP 工具和资源接口提供，让 AI Agent 能够轻松发现并使用区块链功能。所有接受 Ethereum 地址的工具也支持 ENS 名称，并会在后台自动将其解析为地址。

✨ 功能

区块链数据访问

• 支持 30 多个兼容 EVM 的网络
• 链信息，包括 blockNumber、chainId 和 RPC
• 按编号、哈希或最新区块访问 区块数据
• 交易详情和包含已解码日志的收据
• 地址余额，包括原生代币和所有代币标准
• 对易读的 Ethereum 地址进行 ENS 解析（使用 vitalik.eth 代替 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045）

代币服务

• ERC20 代币

  • 获取代币元数据（名称、符号、小数位数、供应量）
  • 查询代币余额
  • 在地址之间转移代币
  • 授权支出额度

• NFT（ERC721）

  • 获取集合和代币元数据
  • 验证代币所有权
  • 在地址之间转移 NFT
  • 获取代币 URI 并统计持有量

• 多代币（ERC1155）

  • 获取代币余额和元数据
  • 按数量转移代币
  • 访问代币 URI

智能合约交互

• 通过 view/pure 函数读取合约状态
• 使用私钥签名的写入服务
• 验证合约，以区分合约和 EOA
• 获取并筛选事件日志

全面的交易支持

• 在所有受支持的网络上转移原生代币
• Gas 估算，用于交易规划
• 交易状态和收据信息
• 提供详细说明的错误处理

🌐 支持的网络

主网

• Ethereum（ETH）
• Optimism（OP）
• Arbitrum（ARB）
• Arbitrum Nova
• Base
• Polygon（MATIC）
• Polygon zkEVM
• Avalanche（AVAX）
• Binance Smart Chain（BSC）
• zkSync Era
• Linea
• Celo
• Gnosis（xDai）
• Fantom（FTM）
• Filecoin（FIL）
• Moonbeam
• Moonriver
• Cronos
• Scroll
• Mantle
• Manta
• Blast
• Fraxtal
• Mode
• Metis
• Kroma
• Zora
• Aurora
• Canto

测试网

• Sepolia
• Optimism Sepolia
• Arbitrum Sepolia
• Base Sepolia
• Polygon Amoy
• Avalanche Fuji
• BSC Testnet
• zkSync Sepolia
• Linea Sepolia
• Scroll Sepolia
• Mantle Sepolia
• Manta Sepolia
• Blast Sepolia
• Fraxtal Testnet
• Mode Testnet
• Metis Sepolia
• Kroma Sepolia
• Zora Sepolia
• Celo Alfajores
• Goerli
• Holesky

🛠️ 前置条件

• Bun 1.0.0 或更高版本
• Node.js 18.0.0 或更高版本（如果不使用 Bun）

📦 安装

# Clone the repository
git clone https://github.com/yourusername/mcp-evm-server.git
cd mcp-evm-server

# Install dependencies with Bun
bun install

# Or with npm
npm install

⚙️ 服务配置

服务使用以下默认配置：

• 默认链 ID：1（Ethereum 主网）
• 服务端口：3001
• 服务主机：0.0.0.0（可通过任何网络接口访问）

这些值在应用程序中硬编码。如果需要修改，可以编辑以下文件：

• 链配置：src/core/chains.ts
• 服务配置：src/server/http-server.ts

🚀 使用方法

使用 npx（无需安装）

你可以使用 npx 直接运行 MCP EVM Server，无需安装：

# Run the server in stdio mode (for CLI tools)
npx @mcpdotdirect/evm-mcp-server

# Run the server in HTTP mode (for web applications)
npx @mcpdotdirect/evm-mcp-server --http

在本地运行服务

使用 stdio 启动服务（用于嵌入命令行工具）：

# Start the stdio server
bun start

# Development mode with auto-reload
bun dev

或者启动带有 SSE 的 HTTP 服务，以用于 Web 应用：

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

连接到服务

使用任何兼容 MCP 的客户端连接到此 MCP 服务。你可以使用 MCP Inspector 进行测试和调试。

从 Cursor 连接

要从 Cursor 连接到 MCP 服务：

1. 打开 Cursor 并前往 Settings（左下角的齿轮图标）

2. 点击左侧边栏中的“Features”

3. 向下滚动到“MCP Servers”部分

4. 点击“Add new MCP server”

5. 输入以下详细信息：

   • 服务名称：evm-mcp-server
   • 类型：command
   • 命令：npx @mcpdotdirect/evm-mcp-server

6. 点击“Save”

连接后，你可以直接在 Cursor 中使用 MCP 服务的功能。该服务会显示在 MCP Servers 列表中，你可以根据需要启用或禁用它。

在 Cursor 中使用 mcp.json

如果要使用可与团队共享或用于多个项目的便携式配置，可以在项目根目录下创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "evm-mcp-server": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server"]
    },
    "evm-mcp-http": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server", "--http"]
    }
  }
}

将此文件放在项目的 .cursor 目录中（如果目录不存在，请创建），Cursor 就会在该项目中工作时自动检测并使用这些 MCP 服务配置。这种方式便于：

1. 与团队共享 MCP 配置
2. 对 MCP 设置进行版本控制
3. 为不同项目使用不同的服务配置

示例：使用带 SSE 的 HTTP 模式

如果你正在开发 Web 应用，并希望连接到带有 Server-Sent Events（SSE）的 HTTP 服务，可以使用以下配置：

{
  "mcpServers": {
    "evm-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

此配置会直接连接到 HTTP 服务的 SSE 端点，适用于：

• 需要从浏览器连接到 MCP 服务的 Web 应用
• 不适合运行本地命令的环境
• 多个用户或应用共享一个 MCP 服务实例

使用此配置：

1. 如果项目根目录下不存在 .cursor 目录，请创建一个
2. 将上述 JSON 保存为 .cursor 目录中的 mcp.json
3. 重启 Cursor 或打开项目
4. Cursor 会检测到该配置，并提示你启用服务

示例：在 Cursor 中使用 MCP 服务

使用 mcp.json 配置 MCP 服务后，你可以轻松地在 Cursor 中使用它。以下是一个工作流示例：

1. 在项目中创建一个新的 JavaScript/TypeScript 文件：

// blockchain-example.js
async function main() {
  try {
    // Get ETH balance for an address using ENS
    console.log("Getting ETH balance for vitalik.eth...");

    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of vitalik.eth on mainnet"
    // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"

    // Cursor will use the MCP server to execute these operations
    // without requiring any additional code from you

    // This is the power of the MCP integration - your AI assistant
    // can directly interact with blockchain data and operations
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

2. 在 Cursor 中打开文件后，你可以让 Cursor：

   • “检查 vitalik.eth 当前的 ETH 余额”
   • “查询 Ethereum 上 USDC 的价格”
   • “显示 Optimism 上的最新区块”
   • “检查 0x1234... 是否为合约地址”

3. Cursor 会使用 MCP 服务执行这些操作，并直接在对话中返回结果。

MCP 服务负责处理所有区块链通信，同时让 Cursor 能够通过自然语言理解并执行与区块链相关的任务。

使用 Claude CLI 连接

如果你使用 Claude CLI，只需两个命令即可连接到 MCP 服务：

# Add the MCP server
claude mcp add evm-mcp-server npx @mcpdotdirect/evm-mcp-server

# Start Claude with the MCP server enabled
claude

示例：使用 ENS 获取代币余额

// Example of using the MCP client to check a token balance using ENS
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
  ownerAddress: "vitalik.eth", // ENS name instead of address
  network: "ethereum",
});

console.log(result);
// {
//   tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
//   owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum",
//   raw: "1000000000",
//   formatted: "1000",
//   symbol: "USDC",
//   decimals: 6
// }

示例：解析 ENS 名称

// Example of using the MCP client to resolve an ENS name to an address
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("resolve-ens", {
  ensName: "vitalik.eth",
  network: "ethereum",
});

console.log(result);
// {
//   ensName: "vitalik.eth",
//   normalizedName: "vitalik.eth",
//   resolvedAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum"
// }

📚 API 参考

工具

服务器为 Agent 提供以下 MCP 工具。所有接受地址参数的工具都支持 Ethereum 地址和 ENS 名称。

代币服务

工具名称	描述	关键参数
get-token-info	获取 ERC20 代币元数据	tokenAddress（地址/ENS）、network
get-token-balance	查看 ERC20 代币余额	tokenAddress（地址/ENS）、ownerAddress（地址/ENS）、network
transfer-token	转移 ERC20 代币	privateKey、tokenAddress（地址/ENS）、toAddress（地址/ENS）、amount、network
approve-token-spending	批准代币额度	privateKey、tokenAddress（地址/ENS）、spenderAddress（地址/ENS）、amount、network
get-nft-info	获取 NFT 元数据	tokenAddress（地址/ENS）、tokenId、network
check-nft-ownership	验证 NFT 所有权	tokenAddress（地址/ENS）、tokenId、ownerAddress（地址/ENS）、network
transfer-nft	转移 NFT	privateKey、tokenAddress（地址/ENS）、tokenId、toAddress（地址/ENS）、network
get-nft-balance	统计拥有的 NFT 数量	tokenAddress（地址/ENS）、ownerAddress（地址/ENS）、network
get-erc1155-token-uri	获取 ERC1155 元数据	tokenAddress（地址/ENS）、tokenId、network
get-erc1155-balance	查看 ERC1155 余额	tokenAddress（地址/ENS）、tokenId、ownerAddress（地址/ENS）、network
transfer-erc1155	转移 ERC1155 代币	privateKey、tokenAddress（地址/ENS）、tokenId、amount、toAddress（地址/ENS）、network

区块链服务

工具名称	描述	关键参数
get-chain-info	获取网络信息	network
get-balance	获取原生代币余额	address（地址/ENS）、network
transfer-eth	发送原生代币	privateKey、to（地址/ENS）、amount、network
get-transaction	获取交易详情	txHash、network
read-contract	读取智能合约状态	contractAddress（地址/ENS）、abi、functionName、args、network
write-contract	写入智能合约	contractAddress（地址/ENS）、abi、functionName、args、privateKey、network
is-contract	检查地址是否为合约	address（地址/ENS）、network
resolve-ens	将 ENS 名称解析为地址	ensName、network

资源

服务器通过以下 MCP 资源 URI 提供区块链数据。所有接受地址的资源 URI 也支持 ENS 名称，并会自动将其解析为地址。

区块链资源

资源 URI 模式	描述
evm://{network}/chain	特定网络的链信息
evm://chain	Ethereum 主网链信息
evm://{network}/block/{blockNumber}	按区块编号获取区块数据
evm://{network}/block/latest	最新区块数据
evm://{network}/address/{address}/balance	原生代币余额
evm://{network}/tx/{txHash}	交易详情
evm://{network}/tx/{txHash}/receipt	包含日志的交易收据

代币资源

资源 URI 模式	描述
evm://{network}/token/{tokenAddress}	ERC20 代币信息
evm://{network}/token/{tokenAddress}/balanceOf/{address}	ERC20 代币余额
evm://{network}/nft/{tokenAddress}/{tokenId}	NFT（ERC721）代币信息
evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}	NFT 所有权验证
evm://{network}/erc1155/{tokenAddress}/{tokenId}/uri	ERC1155 代币 URI
evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}	ERC1155 代币余额

🔒 安全注意事项

• 私钥仅用于交易签名，服务器绝不会存储私钥
• 考虑在生产环境中实现额外的身份验证机制
• 在生产环境中为 HTTP 服务器使用 HTTPS
• 实施速率限制以防止滥用
• 对于高价值服务，可考虑添加确认步骤

📁 项目结构

mcp-evm-server/
├── src/
│   ├── index.ts                # Main stdio server entry point
│   ├── server/                 # Server-related files
│   │   ├── http-server.ts      # HTTP server with SSE
│   │   └── server.ts           # General server setup
│   ├── core/
│   │   ├── chains.ts           # Chain definitions and utilities
│   │   ├── resources.ts        # MCP resources implementation
│   │   ├── tools.ts            # MCP tools implementation
│   │   ├── prompts.ts          # MCP prompts implementation
│   │   └── services/           # Core blockchain services
│   │       ├── index.ts        # Operation exports
│   │       ├── balance.ts      # Balance services
│   │       ├── transfer.ts     # Token transfer services
│   │       ├── utils.ts        # Utility functions
│   │       ├── tokens.ts       # Token metadata services
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── transactions.ts # Transaction services
│   │       └── blocks.ts       # Block services
│   │       └── clients.ts      # RPC client utilities
├── package.json
├── tsconfig.json
└── README.md

🛠️ 开发

如需修改或扩展服务：

1. 在 src/core/services/ 下的相应文件中添加新服务
2. 在 src/core/tools.ts 中注册新工具
3. 在 src/core/resources.ts 中注册新资源
4. 在 src/core/chains.ts 中添加对新网络的支持
5. 如需更改服务器配置，请编辑 src/server/http-server.ts 中的硬编码值

📄 许可证

本项目根据 MIT License 的条款授权。