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函数
• 写入服务，使用私钥签名
• 合约验证，以区分EOA
• 事件日志检索和过滤

全面的交易支持

• 原生代币转移，跨所有支持的网络
• 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
• Flow
• Lumia

测试网

• Sepolia
• Optimism Sepolia
• Arbitrum Sepolia
• Base Sepolia
• Polygon Amoy
• Avalanche Fuji
• BSC 测试网
• zkSync Sepolia
• Linea Sepolia
• Scroll Sepolia
• Mantle Sepolia
• Manta Sepolia
• Blast Sepolia
• Fraxtal 测试网
• Mode 测试网
• Metis Sepolia
• Kroma Sepolia
• Zora Sepolia
• Celo Alfajores
• Goerli
• Holesky
• Flow 测试网
• Filecoin Calibration
• Lumia 测试网

🛠️ 先决条件

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

📦 安装

# 克隆仓库
git clone https://github.com/mcpdotdirect/mcp-evm-server.git
cd mcp-evm-server

# 使用Bun安装依赖
bun install

# 或使用npm
npm install

⚙️ 服务器配置

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

• 默认链ID: 1 (以太坊主网)
• 服务器端口: 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. 点击左侧边栏中的“功能”

3. 向下滚动到“MCP 服务器”部分

4. 点击“添加新的MCP服务器”

5. 输入以下详细信息：

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

6. 点击“保存”

连接后，你可以直接在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("获取vitalik.eth的ETH余额...");
    
    // 当与Cursor一起使用时，你可以简单地要求Cursor：
    // "检查主网上vitalik.eth的ETH余额"
    // 或"从我的钱包转移0.1 ETH到vitalik.eth"
    
    // Cursor将使用MCP服务器执行这些操作
    // 而不需要你编写任何额外的代码
    
    // 这是MCP集成的强大之处——你的AI助手
    // 可以直接与区块链数据和操作交互
  } catch (error) {
    console.error("错误:", error.message);
  }
}

main();

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

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

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客户端检查代币余额的示例
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // 以太坊上的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工具。所有接受地址参数的工具都支持以太坊地址和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代币余额

🔒 安全注意事项

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

📁 项目结构

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 许可证的条款授权。