EVM MCP 服务器

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

📋 目录

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

🔭 概述

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

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

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

✨ 特性

区块链数据访问

• 多链支持，支持 30 多个 EVM 兼容网络
• 链信息，包括 blockNumber、chainId 和 RPC
• 区块数据，可通过编号、哈希或最新获取
• 交易详情和带有解码日志的收据
• 地址余额，适用于原生代币和所有代币标准
• ENS 解析，适用于人类可读的 Ethereum 地址（使用 '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）

📦 安装

# 克隆存储库
git clone https://github.com/yourusername/mcp-evm-server.git
cd mcp-evm-server

# 使用 Bun 安装依赖项
bun install

# 或者使用 npm
npm install

⚙️ 服务器配置

服务器使用以下默认配置：

• 默认链 ID：1 (Ethereum Mainnet)
• 服务器端口：3001
• 服务器主机：0.0.0.0（可从任何网络接口访问）

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

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

🚀 用法

使用 npx（无需安装）

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

# 在 stdio 模式下运行服务器（用于 CLI 工具）
npx @mcpdotdirect/evm-mcp-server

# 在 HTTP 模式下运行服务器（用于 Web 应用程序）
npx @mcpdotdirect/evm-mcp-server --http

在本地运行服务器

使用 stdio 启动服务器（用于嵌入在 CLI 工具中）：

# 启动 stdio 服务器
bun start

# 具有自动重新加载的开发模式
bun dev

或者使用 SSE 启动 HTTP 服务器以用于 Web 应用程序：

# 启动 HTTP 服务器
bun start:http

# 具有自动重新加载的开发模式
bun dev:http

连接到服务器

使用任何 MCP 兼容的客户端连接到此 MCP 服务器。对于测试和调试，您可以使用 MCP Inspector。

从 Cursor 连接

要从 Cursor 连接到 MCP 服务器：

1. 打开 Cursor 并转到设置（左下角的齿轮图标）

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

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

4. 单击“Add new MCP server”

5. 输入以下详细信息：

   • Server name: evm-mcp-server
   • Type: command
   • Command: npx @mcpdotdirect/evm-mcp-server

6. 单击“Save”

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

将 mcp.json 与 Cursor 结合使用

对于可以与您的团队共享或跨项目使用的更便携的配置，您可以在项目的根目录中创建一个 .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 应用程序并希望使用服务器发送事件 (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 {
    // 使用 ENS 获取地址的 ETH 余额
    console.log("Getting ETH balance for vitalik.eth...");

    // 与 Cursor 一起使用时，您可以简单地要求 Cursor：
    // "Check the ETH balance of vitalik.eth on mainnet"
    // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"

    // Cursor 将使用 MCP 服务器来执行这些操作
    // 而无需您提供任何其他代码

    // 这就是 MCP 集成的强大之处 - 您的 AI 助手
    // 可以直接与区块链数据和操作进行交互
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

2. 在 Cursor 中打开文件后，您可以要求 Cursor：

   • "Check the current ETH balance of vitalik.eth"
   • "Look up the price of USDC on Ethereum"
   • "Show me the latest block on Optimism"
   • "Check if 0x1234... is a contract address"

3. Cursor 将使用 MCP 服务器来执行这些操作，并将结果直接返回到您的对话中。

MCP 服务器处理所有区块链通信，同时允许 Cursor 通过自然语言理解和执行与区块链相关的任务。

使用 Claude CLI 连接

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

# 添加 MCP 服务器
claude mcp add evm-mcp-server npx @mcpdotdirect/evm-mcp-server

# 启动 Claude 并启用 MCP 服务器
claude

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

// 使用 MCP 客户端检查使用 ENS 的代币余额的示例
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // Ethereum 上的 USDC
  ownerAddress: "vitalik.eth", // ENS 名称而不是地址
  network: "ethereum",
});

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

示例：解析 ENS 名称

// 使用 MCP 客户端将 ENS 名称解析为地址的示例
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 工具。 所有接受地址参数的工具都支持 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 代币余额

🔒 安全注意事项

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

📁 项目结构

mcp-evm-server/
├── src/
│   ├── index.ts                # 主要 stdio 服务器入口点
│   ├── server/                 # 与服务器相关的文件
│   │   ├── http-server.ts      # 带有 SSE 的 HTTP 服务器
│   │   └── server.ts           # 常规服务器设置
│   ├── core/
│   │   ├── chains.ts           # 链定义和实用程序
│   │   ├── resources.ts        # MCP 资源实现
│   │   ├── tools.ts            # MCP 工具实现
│   │   ├── prompts.ts          # MCP 提示实现
│   │   └── services/           # 核心区块链服务
│   │       ├── index.ts        # 操作导出
│   │       ├── balance.ts      # 余额服务
│   │       ├── transfer.ts     # 代币转移服务
│   │       ├── utils.ts        # 实用函数
│   │       ├── tokens.ts       # 代币元数据服务
│   │       ├── contracts.ts    # 合约交互
│   │       ├── transactions.ts # 交易服务
│   │       └── blocks.ts       # 区块服务
│   │       └── clients.ts      # RPC 客户端实用程序
├── 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 许可证 的条款获得许可。