@sinco-lab/evm-mcp-server

English Document

一个基于模型上下文协议 (MCP) 和 Viem 的 EVM 交互服务网关，使 AI 代理或服务能够安全地与配置的 EVM 兼容区块链进行交互。

📋 目录

• 概述
• 特性
• 前提条件
• 安装
• 配置
• 使用
• 从客户端连接 (Cursor, Claude)
• 可用工具
• 安全注意事项
• 项目结构
• 开发脚本
• 许可证

🔭 概述

本项目提供了一个模型上下文协议 (MCP) 服务器，旨在充当与 EVM 兼容区块链交互的网关。它利用强大的 Viem 库进行区块链交互，并使用 MCP SDK 将这些功能公开为可供 AI 代理或其他 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 文件并启动连接到服务器脚本 (build/evm.js) 的 inspector，传递必要的环境变量。

🔌 从客户端连接 (Cursor, Claude)

您可以配置像 Cursor 或 Claude Desktop 应用程序这样的客户端来自动启动并连接到此 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：

// 通用 mcpServers 结构
{
  "mcpServers": {
    // 选项 1：运行本地构建的服务器
    "local-evm-mcp-dev": {
      "command": "node", // 直接使用 node
      "args": [
        "/path/to/your/project/build/evm.js" // 使用绝对路径
      ],
      "env": {
        // 警告：安全风险！使用新密钥（请参阅安全注意事项）。
        "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
        "RPC_PROVIDER_URL": "YOUR_RPC_PROVIDER_URL_HERE"
      },
    },
    // 选项 2：通过 npx 运行已发布的包（如果适用）
    "npx-evm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@sinco-lab/evm-mcp-server" // 使用您发布的包名称
      ],
      "env": {
        // 警告：安全风险！使用新密钥（请参阅安全注意事项）。
        "WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE",
        "RPC_PROVIDER_URL": "YOUR_RPC_PROVIDER_URL_HERE"
      }
    }
  }
}

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

从 Cursor 连接（推荐方法）

配置 Cursor 的推荐方法是在您的项目中使用 .cursor/mcp.json 文件。

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

(可以通过 Cursor 设置 UI 进行手动设置，但对于特定于项目的配置，不太推荐使用。)

从 Claude Desktop 应用程序连接

如果 Claude Desktop 应用程序支持配置文件（请查看其文档以获取确切的路径和格式，通常类似于下面的示例）：

1. 找到或创建 Claude Desktop 配置文件（例如，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 Desktop 应用程序运行的环境是正确的。

3. 重新启动 Claude Desktop 应用程序。

建议： 优先使用带有 env 字段的配置文件方法（Cursor 的 mcp.json 或 Claude Desktop 的配置文件），同时注意在配置文件中存储密钥的固有风险。

🛠️ 可用工具

服务器当前通过模型上下文协议公开以下工具：

工具名称	描述
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/                # 服务器和工具的核心源代码
│   ├── evm.ts          # 主要服务器入口点逻辑
│   └── evm-tools.ts    # 所有 MCP 工具的定义和逻辑
├── test/               # 测试客户端代码
│   └── client.ts       # 用于测试服务器的示例 MCP 客户端
├── build/              # 编译后的 JavaScript 输出（由 `pnpm run build` 生成）
├── .env.example        # 示例环境变量文件模板
├── .env                # 环境变量（已忽略 Git，需要创建）
├── .gitignore
├── package.json        # 项目清单和依赖项
├── pnpm-lock.yaml      # pnpm 的锁定文件
├── tsconfig.json       # TypeScript 编译器配置
└── README.md           # 此文件
└── README.zh.md        # 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 许可证 的条款获得许可。