EVM MCP Server

EVM MCP 服务

一款功能全面的模型上下文协议（MCP）服务，为 60 多个兼容 EVM 的网络提供区块链服务。该服务通过 22 个工具和 10 个 AI 引导提示词，为 AI Agent 提供统一接口，使其能够与 Ethereum、Optimism、Arbitrum、Base、Polygon 及许多其他 EVM 链交互。

📋 目录

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

🔭 概述

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

• 读取区块链状态（余额、交易、区块等）
• 与智能合约交互，并从区块浏览器自动获取 ABI
• 转移代币（原生代币、ERC20、ERC721、ERC1155）
• 查询代币元数据和余额
• 提供覆盖 60 多个 EVM 网络的链专属服务（34 个主网 + 26 个测试网）
• 为所有地址参数提供 ENS 名称解析（可使用“vitalik.eth”等易读名称代替地址）
• 通过 AI 友好的提示词引导 Agent 完成复杂工作流

所有服务都通过统一的 MCP 工具、资源和提示词接口提供，使 AI Agent 能够轻松发现并使用区块链功能。所有接受 Ethereum 地址的工具也支持 ENS 名称，并会在后台自动将其解析为地址。该服务还支持智能 ABI 获取，无需事先了解合约 ABI。

✨ 功能

区块链数据访问

• 多链支持，覆盖 60 多个兼容 EVM 的网络（34 个主网 + 26 个测试网）
• 链信息，包括 blockNumber、chainId 和 RPC
• 按区块号、哈希或最新区块访问区块数据
• 交易详情和包含已解码日志的收据
• 地址余额，包括原生代币及所有代币标准
• ENS 解析，支持将易读的 Ethereum 地址名称（例如使用“vitalik.eth”代替“0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045”）

代币服务

• ERC20 代币

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

• NFT（ERC721）

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

• 多代币（ERC1155）

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

智能合约交互

• 通过 view/pure 函数读取合约状态
• 向合约写入——通过自动获取 ABI 执行任何更改状态的函数
• 合约验证，用于区分合约与 EOA
• 获取并筛选事件日志
• 从 Etherscan v2 API 跨所有 60 多个网络自动获取 ABI（无需事先了解 ABI）
• ABI 解析和验证，并发现函数

全面的交易支持

• 灵活的钱包支持 - 可使用私钥或助记词（BIP-39）进行配置，并支持 HD 路径
• 原生代币转账，适用于所有支持的网络
• Gas 估算，用于交易规划
• 交易状态和收据详情
• 错误处理，提供清晰的错误消息

消息签名功能

• 个人消息签名 - 签署任意消息，用于身份验证和验证
• EIP-712 类型化数据签名 - 签署结构化数据，用于免 Gas 交易和元交易
• SIWE 支持 - 启用 Sign-In With Ethereum 身份验证流程
• Permit 签名 - 创建链下授权，用于免 Gas 代币操作
• 元交易支持 - 为中继服务和免 Gas 转账签署交易数据

AI 引导的工作流（提示词）

• 交易准备 - 为转账规划和执行提供指导
• 钱包分析 - 用于分析钱包活动和持仓的工具
• 智能合约探索 - 交互式获取 ABI 并分析合约
• 合约交互 - 安全地执行智能合约上的写入操作
• 网络信息 - 了解 EVM 网络并进行比较
• 授权审计 - 检查和管理代币授权
• 错误诊断 - 排查交易失败问题

🌐 支持的网络

主网

• 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
• Flow
• Lumia

测试网

• 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
• Flow Testnet
• Filecoin Calibration
• Lumia Testnet

🛠️ 前提条件

• Bun 1.0.0 或更高版本（推荐）
• Node.js 20.0.0 或更高版本（如果不使用 Bun）
• 可选：Etherscan API key，用于获取 ABI

📦 安装

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

# Install dependencies with Bun
bun install

# Or with npm
npm install

⚙️ 配置

环境变量

服务使用以下环境变量。对于写入操作和 ABI 获取，必须配置这些变量：

钱包配置（用于写入操作）

你可以使用私钥或助记词来配置钱包：

选项 1：私钥

export EVM_PRIVATE_KEY="0x..." # Your private key in hex format (with or without 0x prefix)

选项 2：助记词（推荐用于 HD 钱包）

export EVM_MNEMONIC="word1 word2 word3 ... word12" # Your 12 or 24 word BIP-39 mnemonic
export EVM_ACCOUNT_INDEX="0" # Optional: Account index for HD wallet derivation (default: 0)

助记词选项支持分层确定性（HD）钱包派生：

• 使用 BIP-39 标准助记词（12 或 24 个单词）
• 支持 BIP-44 派生路径：m/44'/60'/0'/0/{accountIndex}
• EVM_ACCOUNT_INDEX 允许你从同一助记词派生不同账户
• 默认账户索引为 0（第一个账户）

钱包用于：

• 转移原生代币（transfer_native 工具）
• 转移 ERC20 代币（transfer_erc20 工具）
• 授权代币支出（approve_token_spending 工具）
• 向智能合约写入（write_contract 工具）
• 为身份验证签署消息（sign_message 工具）
• 为免 Gas 交易签署结构化数据（sign_typed_data 工具）

⚠️ 安全性：

• 切勿将私钥或助记词提交到版本控制系统
• 使用环境变量或安全的密钥管理系统
• 妥善保管助记词，它们可访问所有派生账户
• 考虑为不同用途使用不同的账户索引

API 密钥（用于获取 ABI）

export ETHERSCAN_API_KEY="your-api-key-here"

此 API 密钥为可选项，但以下功能需要使用：

• 从区块浏览器自动获取 ABI（get_contract_abi 工具）
• 读取合约时自动获取 ABI（带有 abiJson 参数的 read_contract 工具）
• fetch_and_analyze_abi 提示词

从以下平台获取免费 API 密钥：

• Etherscan - 适用于 Ethereum 及兼容链
• 同一个密钥可通过 Etherscan v2 API 用于 60 多个 EVM 网络

服务配置

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

• 默认链 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 应用，并希望通过服务器发送事件（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"
// }

示例：使用 Multicall 批量调用

// Example of using multicall to batch multiple contract reads in a single RPC call
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("multicall", {
  network: "ethereum",
  calls: [
    {
      contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      functionName: "balanceOf",
      args: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
    },
    {
      contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      functionName: "symbol",
    },
    {
      contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      functionName: "decimals",
    },
  ],
});

console.log(result);
// {
//   network: "ethereum",
//   totalCalls: 3,
//   successfulCalls: 3,
//   failedCalls: 0,
//   results: [
//     { contractAddress: "0xA0b...", functionName: "balanceOf", result: "1000000000", status: "success" },
//     { contractAddress: "0xA0b...", functionName: "symbol", result: "USDC", status: "success" },
//     { contractAddress: "0xA0b...", functionName: "decimals", result: "6", status: "success" }
//   ]
// }

📚 API 参考

工具

此服务为 Agent 提供 25 个专用的 MCP 工具。所有接受地址参数的工具均支持 Ethereum 地址和 ENS 名称。

钱包信息

工具名称	描述	关键参数
get_wallet_address	获取已配置的钱包地址（来自 EVM_PRIVATE_KEY）	无

网络信息

工具名称	描述	关键参数
get_chain_info	获取网络信息	network
get_supported_networks	列出所有受支持的 EVM 网络	无
get_gas_price	获取网络当前的 Gas 价格	network

ENS 服务

工具名称	描述	关键参数
resolve_ens_name	将 ENS 名称解析为地址	ensName、network
lookup_ens_address	反向查询地址对应的 ENS 名称	address、network

区块与交易信息

工具名称	描述	关键参数
get_block	获取区块数据	blockNumber 或 blockHash、network
get_latest_block	获取最新区块数据	network
get_transaction	获取交易详情	txHash、network
get_transaction_receipt	获取带日志的交易收据	txHash、network
wait_for_transaction	等待交易确认	txHash、confirmations、network

余额与代币信息

工具名称	描述	关键参数
get_balance	获取原生代币余额	address（地址/ENS）、network
get_token_balance	查询 ERC20 代币余额	tokenAddress（地址/ENS）、ownerAddress（地址/ENS）、network
get_allowance	查询代币支出额度	tokenAddress（地址/ENS）、ownerAddress（地址/ENS）、spenderAddress（地址/ENS）、network

智能合约交互

工具名称	描述	关键参数
get_contract_abi	从区块浏览器获取合约 ABI（支持 60 多个网络）	contractAddress（地址/ENS）、network
read_contract	读取智能合约状态（如有需要会自动获取 ABI）	contractAddress、functionName、args[]、abiJson（可选）、network
write_contract	执行会更改状态的函数（如有需要会自动获取 ABI）	contractAddress、functionName、args[]、value（可选）、abiJson（可选）、network
multicall	将多个读取调用批量合并为单个 RPC 请求（使用 Multicall3）	calls[]（合约调用数组）、allowFailure（可选）、network

代币转账

工具名称	描述	关键参数
transfer_native	发送原生代币（ETH 等）	to（地址/ENS）、amount、network
transfer_erc20	转账 ERC20 代币	tokenAddress（地址/ENS）、to（地址/ENS）、amount、network
approve_token_spending	批准代币支出额度	tokenAddress（地址/ENS）、spenderAddress（地址/ENS）、amount、network

NFT 服务

工具名称	描述	关键参数
get_nft_info	获取 NFT（ERC721）元数据	tokenAddress（地址/ENS）、tokenId、network
get_erc1155_balance	查询 ERC1155 余额	tokenAddress（地址/ENS）、tokenId、ownerAddress（地址/ENS）、network

消息签名

工具名称	描述	关键参数
sign_message	为身份验证和验证签署任意消息（SIWE、链下签名）	message
sign_typed_data	为免 Gas 交易、授权和元交易签署 EIP-712 结构化数据	domainJson、typesJson、primaryType、messageJson

资源

该服务通过以下 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 许可证 的条款授权。