@sinco-lab/evm-mcp-server

中文文档

@sinco-lab/evm-mcp-server

一个基于 Model Context Protocol（MCP）和 Viem 的 EVM 交互服务网关，可让 AI Agent 或服务安全地与配置的 EVM 兼容区块链交互。

📋 目录

• 概览
• 功能
• 前提条件
• 安装
• 配置
• 使用方法
• 从客户端连接（Cursor、Claude）
• 可用工具
• 安全注意事项
• 项目结构
• 开发脚本
• 许可证

🔭 概览

本项目提供了一个 Model Context Protocol（MCP）服务，旨在作为与 EVM 兼容区块链交互的网关。它使用强大的 Viem 库进行区块链交互，并通过 MCP SDK 将这些功能公开为工具，供 AI Agent 或其他 MCP 客户端使用。

该服务连接到通过环境变量配置的特定 EVM 链，并允许客户端通过标准化的 MCP 接口执行各种读取和写入操作。

✨ 功能

• MCP 集成：将 EVM 功能公开为标准 MCP 工具。
• Viem 驱动：使用现代、高效的 Viem 库，实现可靠的 EVM 交互。
• 端点可配置：通过环境配置中定义的 RPC URL 连接到任意 EVM 兼容链。
• 核心 EVM 操作：提供常见任务所需的工具，例如查询余额、转移原生代币和 ERC20 代币、签署消息，以及与合约交互（读取授权额度、批准等）。
• 类型安全：完全使用 TypeScript 开发，提升可维护性和开发体验。

🛠️ 前提条件

• Node.js 版本 18.0.0 或更高。
• pnpm 包管理器。

📦 安装

1. 克隆仓库：

   git clone https://github.com/sinco-lab/evm-mcp-server.git
   cd evm-mcp-server
   

2. 使用 pnpm 安装依赖：

   pnpm install
   

⚙️ 配置

配置主要通过环境变量进行。该服务需要：

• WALLET_PRIVATE_KEY：服务将使用的钱包私钥（以 0x 开头）。请妥善保管！
• RPC_PROVIDER_URL：目标 EVM 网络的 JSON-RPC 端点 URL。

这些变量可以通过 .env 文件提供（用于测试客户端和调试），也可以直接写入客户端的 MCP 服务配置中（见下文）。

🚀 使用方法

构建项目

将 TypeScript 源代码编译为 JavaScript：

pnpm run build

此命令会生成包含 build/evm.js 的 build 目录。

手动启动 MCP 服务（Stdio 模式）

如果使用 .env 文件进行配置：

1. 将 .env.example 复制为 .env。
2. 在 .env 中填写 WALLET_PRIVATE_KEY 和 RPC_PROVIDER_URL。
3. 运行服务：

   # 如果当前目录或父目录中存在 .env，则自动加载
   node build/evm.js
   

   （注意：node 本身不会加载 .env，但 src/evm.ts 中使用的 dotenv 包会这样做）

运行示例测试客户端

此项目包含一个简单的测试客户端（test/client.ts），它使用 StdioClientTransport，根据配置自动启动服务进程（node build/evm.js）。

前置条件：

1. 构建项目：pnpm run build
2. 创建并配置 .env 文件（客户端脚本会读取此文件）。

运行客户端：

pnpm run test

此命令使用 tsx（通过 package.json）执行 test/client.ts。客户端脚本会读取 .env、启动服务进程、通过 stdio 连接到该进程、列出可用工具，并调用 getChain 工具。

使用 MCP Inspector 调试

需要配置好的 .env 文件和已构建的项目。

pnpm run debug

此脚本会读取 .env 文件并启动 Inspector，连接到服务脚本（build/evm.js），同时传入必要的环境变量。

🔌 从客户端连接（Cursor、Claude）

你可以配置 Cursor 或 Claude 桌面应用等客户端，使其自动启动并连接到此 MCP 服务。

前置条件：

1. 安装依赖：pnpm install
2. 构建项目：pnpm run build

安全警告： 以下配置会将 WALLET_PRIVATE_KEY 和 RPC_PROVIDER_URL 直接写入配置文件（.cursor/mcp.json 或 claude_desktop_config.json）。这些文件的存储安全性可能不如 .env 文件，并且可能会在无意中同步或备份。**将敏感信息直接写入这些配置文件前，请了解相关风险。**如有更高的安全需求，请考虑采用此处未介绍的其他密钥管理策略。

常见的 mcpServers 配置结构

以下是配置 MCP 服务所需的基本 JSON 结构，可用于 Cursor 和 Claude Desktop：

// Common mcpServers structure
{
  "mcpServers": {
    // Option 1: Run locally built server
    "local-evm-mcp-dev": {
      "command": "node", // Use node directly
      "args": [
        "/path/to/your/project/build/evm.js" // Use absolute path
      ],
      "env": {
        // WARNING: Security risk! Use a new key (see Security Considerations).
        "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
        "RPC_PROVIDER_URL": "YOUR_RPC_PROVIDER_URL_HERE"
      },
    },
    // Option 2: Run published package via npx (if applicable)
    "npx-evm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@sinco-lab/evm-mcp-server" // Use your published package name
      ],
      "env": {
        // WARNING: Security risk! Use a new key (see Security Considerations).
        "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
        "RPC_PROVIDER_URL": "YOUR_RPC_PROVIDER_URL_HERE"
      }
    }
  }
}

重要： 标准 JSON 文件不允许包含注释。使用此配置前，请删除所有以 // 开头的行。

从 Cursor 连接（推荐方法）

推荐在项目中使用 .cursor/mcp.json 文件配置 Cursor。

1. 如果项目根目录中不存在 .cursor 目录，请创建该目录。
2. 在 .cursor 目录中创建名为 mcp.json 的文件。
3. 将上方的常见 mcpServers 配置结构复制到 mcp.json 文件中。将占位值替换为你自己的私钥和 RPC URL，并确保已删除所有注释。
4. 重启 Cursor 或重新加载项目。在 Cursor 的 MCP 设置中启用所需的服务（local-evm-mcp-dev 或 npx-evm-mcp）。

（也可以通过 Cursor 设置界面手动配置，但对于项目专属配置，此方法不太推荐。）

从 Claude 桌面应用连接

如果 Claude 桌面应用支持配置文件（请查阅其文档，确认确切路径和格式；通常与以下示例相似）：

1. 找到或创建 Claude 桌面应用的配置文件（例如，macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，或 Windows 上的 %APPDATA%\\Claude\\claude_desktop_config.json）。

2. 将上方常见 mcpServers 配置结构中的 "mcpServers" 键及其内容合并到 Claude 主配置文件中。将占位符替换为你自己的私钥和 RPC URL，并确保已删除注释。如果文件已存在，请谨慎合并 JSON 对象，以免破坏现有的 Claude 设置。

   注意：如常见配置结构中的注释所述，请确保 command、args 设置适用于运行 Claude 桌面应用的环境。

3. 重启 Claude 桌面应用。

**建议：**优先使用配置文件方式（Cursor 的 mcp.json 或 Claude Desktop 的配置文件），并通过 env 字段配置，同时注意将机密信息存储在配置文件中的固有风险。

🛠️ 可用工具

服务器目前通过 Model Context Protocol 提供以下工具：

工具名称	描述
getAddress	获取服务器上配置的已连接钱包地址。
getChain	获取服务器连接的链 ID 和名称。
getBalance	获取指定地址（或服务器钱包）的原生代币余额。
signMessage	使用服务器配置的钱包对消息签名。
sendNativeToken	将原生代币（例如 ETH）从服务器钱包发送给收款方。
getTokenBalance	获取指定所有者地址的 ERC20 代币余额。
transferToken	从服务器钱包发送指定数量的 ERC20 代币。
getTokenTotalSupply	获取 ERC20 代币的总供应量。
getTokenAllowance	获取所有者为 ERC20 代币授予支出方的额度。
approveToken	授权支出方从服务器钱包提取 ERC20 代币。
revokeApproval	撤销（设为 0）ERC20 代币对支出方的授权额度。
transferTokenFrom	将 ERC20 代币从一个地址转至另一个地址（需要事先授权）。
convertToBaseUnit	将十进制代币数量转换为基本单位表示形式（例如 wei）。
convertFromBaseUnit	将基本单位表示形式的代币数量转换为十进制字符串。

（详细的参数和返回值架构请参阅 src/evm-tools.ts）

🔒 安全注意事项

• 私钥管理：直接将 WALLET_PRIVATE_KEY 写入配置文件（.cursor/mcp.json、claude_desktop_config.json）或使用 .env 文件都存在安全风险。切勿将包含私钥的文件提交到版本控制系统。 在生产环境或涉及高价值资产的场景中，请使用专用的密钥管理解决方案。 为降低风险，强烈建议创建一个新的专用钱包私钥，用于开发和测试。请勿在此处使用持有大量资金的主钱包密钥。
• RPC 端点安全：确保 RPC_PROVIDER_URL 指向可信节点。
• 访问控制：以 stdio 模式运行的服务器没有内置访问控制。请保护运行服务器进程的环境。

📁 项目结构

evm-mcp-server/
├── src/                # Core source code for the server and tools
│   ├── evm.ts          # Main server entry point logic
│   └── evm-tools.ts    # Definitions and logic for all MCP tools
├── test/               # Test client code
│   └── client.ts       # Example MCP client for testing the server
├── build/              # Compiled JavaScript output (generated by `pnpm run build`)
├── .env.example        # Example environment file template
├── .env                # Environment variables (Gitignored, needs creation)
├── .gitignore
├── package.json        # Project manifest and dependencies
├── pnpm-lock.yaml      # Lockfile for pnpm
├── tsconfig.json       # TypeScript compiler configuration
└── README.md           # This file
└── README.zh.md        # Chinese version of README

💻 开发脚本

package.json 中定义的主要脚本：

• pnpm run build：将 src/ 中的 TypeScript 代码编译为 build/ 中的 JavaScript。
• pnpm run test：使用 tsx 运行示例测试客户端（test/client.ts）。客户端会自行启动服务器进程（需要 .env）。
• pnpm run clean：删除 build/ 目录。
• pnpm run debug：启动服务器并连接 MCP Inspector 进行调试（需要 .env）。
• pnpm run prepublishOnly：发布到 npm 前自动清理并构建项目。

📄 许可证

本项目遵循 MIT 许可证。