EVM MCP 服务器

一个全面的模型上下文协议（MCP）服务器，提供跨多个EVM兼容网络的区块链服务。该服务器使AI代理能够通过统一的接口与以太坊、Optimism、Arbitrum、Base、Polygon以及许多其他EVM链进行交互。

📋 目录

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

🔭 概述

MCP EVM 服务器利用模型上下文协议为AI代理提供区块链服务。它支持广泛的服务，包括：

• 读取区块链状态（余额、交易、区块等）
• 与智能合约交互
• 转移代币（原生代币、ERC20、ERC721、ERC1155）
• 查询代币元数据和余额
• 跨30多个EVM网络的链特定服务
• ENS名称解析，适用于所有地址参数（可以使用如'vitalik.eth'这样的人可读名称，而不仅仅是地址）

所有服务都通过一致的MCP工具和资源接口暴露出来，使得AI代理能够轻松发现并使用区块链功能。每个接受以太坊地址的工具也支持ENS名称，在后台自动将其解析为地址。

✨ 特性

区块链数据访问

• 多链支持，支持30多个EVM兼容网络
• 链信息，包括blockNumber、chainId和RPCs
• 区块数据，按编号、哈希或最新获取
• 交易详情及解码后的日志
• 地址余额，包括原生代币和所有代币标准
• ENS解析，用于人可读的以太坊地址（使用'vitalik.eth'而不是'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'）

代币服务

• ERC20 代币

  • 获取代币元数据（名称、符号、小数点、供应量）
  • 检查代币余额
  • 在地址之间转移代币
  • 批准支出限额

• NFTs (ERC721)

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

• 多代币 (ERC1155)

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

智能合约交互

... （此处省略了未提供的原文内容）

• 读取合约状态 通过 view/pure 函数
• 编写服务 使用私钥签名
• 合约验证 以区分 EOAs
• 事件日志 检索和过滤

全面的交易支持

• 所有支持网络上的原生代币转账
• Gas 估算 用于交易规划
• 交易状态 和回执信息
• 错误处理 带有描述性消息

🌐 支持的网络

主网

• 以太坊 (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 (以太坊主网)
• 服务器端口: 3001
• 服务器主机: 0.0.0.0（可从任何网络接口访问）

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

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

🚀 使用方法

使用 npx（无需安装）

您可以直接使用 npx 运行 MCP EVM 服务器，而无需安装：

# 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 启动服务器（用于嵌入 CLI 工具）：

# 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 并转到设置（左下角的齿轮图标）
2. 点击左侧边栏中的“功能”
3. 向下滚动到“MCP 服务器”部分
4. 点击“添加新的 MCP 服务器”
5. 输入以下详细信息：
   • 服务器名称: evm-mcp-server
   • 类型: command
   • 命令: npx @mcpdotdirect/evm-mcp-server
6. 点击“保存”

一旦连接成功，您可以在 Cursor 中直接使用 MCP 服务器的功能。该服务器将出现在 MCP 服务器列表中，并可以根据需要启用或禁用。

在 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. 为不同的项目使用不同的服务器配置

变得非常容易。

示例：HTTP 模式与 SSE

如果您正在开发 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();

1. 在 Cursor 中打开文件后，您可以要求 Cursor 执行以下操作：

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

2. 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 获取 Token 余额

// 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 参考

工具

服务器为代理提供了以下 MCP 工具。所有接受地址参数的工具都支持以太坊地址和 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	以太坊主网链信息
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 代币余额

🔒 安全注意事项

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

📁 项目结构

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 的条款获得许可。