MCP Ethers 钱包

一个使用 ethers.js v6 提供以太坊钱包功能的模型上下文协议 (MCP) 服务器。

概述

MCP Ethers 钱包通过模型上下文协议向 LLM 应用程序公开以太坊功能。它提供以下工具：

• 网络信息和管理
• 钱包创建和管理
• 交易创建和发送
• 合约交互 (ERC20, ERC721, ERC1155)
• ENS 解析
• 单位转换
• Gas 估算
• 交易历史

此服务器遵循 MCP 规范，使其与任何 MCP 客户端（例如 Claude Desktop）兼容。

与 MCP 工具一起使用

要将此用作 MCP 服务器与 Claude Desktop 等工具一起使用，请使用以下配置：

{
  "ethers": {
    "command": "node",
    "args": [
      "pathTo/ethers-server/build/src/mcpServer.js"
    ],
    "env": {
      "ALCHEMY_API_KEY": "key goes here",
      "INFURA_API_KEY": "key goes here"
    }
  }
}

将 pathTo/ethers-server 替换为您的实际安装目录，并添加您的 API 密钥。

安装

# 克隆仓库
git clone https://github.com/yourusername/ethers-server.git
cd ethers-server

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

快速开始

启动服务器

# 使用 Node.js
npm start

# 使用 Bun (推荐，性能更快)
bun start

与 Claude Desktop 一起使用

1. 配置 Claude Desktop 以使用此服务器：

   • 转到 Settings > Model Context Protocol
   • 将 Command 设置为：node path/to/ethers-server/build/src/mcpServer.js

2. 在您的 Claude 对话中使用 Ethers 工具。

使用 MCP Inspector 进行测试

MCP Inspector 是一个用于测试和调试 MCP 服务器的工具。

# 全局安装 MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 使用您的服务器运行它
mcp-inspector --command "node build/src/mcpServer.js"

配置

环境变量

在根目录中创建一个 .env 文件，内容如下：

# 必需
ALCHEMY_API_KEY=your_alchemy_api_key
INFURA_API_KEY=your_infura_api_key

# 可选
DEFAULT_NETWORK=mainnet  # 默认值: mainnet
LOG_LEVEL=info           # 默认值: info (选项: error, warn, info, debug)

网络配置

服务器支持多个以太坊和 EVM 兼容网络。 支持的网络在 src/config/networkList.ts 中定义：

主网网络

• Ethereum (ETH)
• Polygon PoS (POL)
• Arbitrum (ETH)
• Arbitrum Nova (ETH)
• Optimism (ETH)
• Avalanche C-Chain (AVAX)
• Base (ETH)
• Polygon zkEVM (ETH)
• Linea (ETH)
• BNB Smart Chain (BNB)
• Scroll (ETH)
• Rari Chain Mainnet (ETH)
• Berachain (BERA)
• Sonic Mainnet (S)

测试网网络

• Monad Testnet (MON)
• MEGA Testnet (ETH)

您可以在使用工具时使用 provider 参数指定网络，例如，"provider": "polygon" 或 "provider": "bera"。

自定义 RPC URL

您也可以使用自定义 RPC URL：

"provider": "https://my-custom-rpc.example.com"

可用工具

核心网络工具

• getSupportedNetworks: 获取所有支持的网络及其配置的列表
• getBlockNumber: 获取当前区块号
• getBlockDetails: 获取有关区块的详细信息
• getTransactionDetails: 获取有关交易的详细信息
• getGasPrice: 获取当前 gas 价格
• getFeeData: 获取当前网络费用数据

钱包工具

• generateWallet: 生成一个新的以太坊钱包
• loadWallet: 从私钥加载现有钱包
• checkWalletExists: 检查服务器上是否配置了钱包
• getWalletBalance: 获取钱包的 ETH 余额
• getWalletTransactionCount: 获取地址发送的交易数量
• signMessage: 使用加载的钱包签署消息
• ethSign: 使用以太坊 eth_sign 方法签署数据（旧版）

合约工具

• getContractCode: 获取合约的字节码
• callContractMethod: 调用合约上的只读方法
• estimateGas: 估算交易的 gas

ENS 工具

• lookupAddress: 获取地址的 ENS 名称
• resolveName: 获取 ENS 名称的地址

单位转换工具

• formatEther: 将 wei 值转换为以太币的十进制字符串
• parseEther: 将以太币值转换为 wei
• formatUnits: 将值转换为具有指定单位的十进制字符串

ERC20 工具

• erc20GetTokenInfo: 获取基本 token 信息（名称、符号、小数位数）
• erc20GetBalance: 获取地址的 token 余额
• erc20Transfer: 在帐户之间转移 token
• erc20GetAllowance: 获取 token 授权额度
• erc20Approve: 批准另一个地址花费 token

ERC721 工具

• erc721GetTokenInfo: 获取基本 NFT 集合信息
• erc721GetBalance: 获取地址的 NFT 余额
• erc721OwnerOf: 获取特定 NFT 的所有者
• erc721GetTokenURI: 获取 NFT 的 token URI 元数据
• erc721Transfer: 将 NFT 转移到另一个地址
• erc721SafeTransfer: 安全地将 NFT 转移到另一个地址

ERC1155 工具

• erc1155GetTokenInfo: 获取基本多 token 信息
• erc1155GetBalance: 获取地址和 token ID 的 token 余额
• erc1155GetBatchBalance: 在单个调用中获取多个 token 余额
• erc1155GetURI: 获取 token 的元数据 URI
• erc1155SafeTransfer: 安全地将 token 转移到另一个地址
• erc1155SafeBatchTransfer: 在单个调用中安全地转移多个 token

工具使用示例

获取网络信息

{
  "name": "getSupportedNetworks",
  "arguments": {}
}

获取钱包余额

{
  "name": "getWalletBalance",
  "arguments": {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "provider": "mainnet"
  }
}

获取 ERC20 Token 信息

{
  "name": "erc20GetTokenInfo",
  "arguments": {
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "provider": "mainnet"
  }
}

调用合约方法

{
  "name": "callContractMethod",
  "arguments": {
    "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "methodName": "symbol",
    "params": [],
    "abi": ["function symbol() view returns (string)"],
    "provider": "mainnet"
  }
}

缓存

服务器为某些操作实现了缓存，以提高性能并减少 API 调用：

• Token 信息（名称、符号、小数位数）
• Token 余额
• 合约方法调用

缓存使用生存时间 (TTL) 机制，该机制会在可配置的时间段后自动过期条目。

速率限制

服务器对某些操作实施了速率限制：

• 写入操作（转移、批准）
• 钱包生成
• 合约交互

这可以防止滥用并确保服务器保持响应。

错误处理

服务器包括全面的错误处理：

• 特定错误类型的自定义错误类
• 详细的错误消息
• 适当的 HTTP 状态代码
• 安全的错误序列化以防止敏感数据泄露

开发

构建

npm run build

测试

服务器包括全面的测试套件：

使用 Bun 运行所有测试（推荐）

# 在单独的终端中启动 Hardhat 节点
npx hardhat node

# 运行所有测试
bun test

运行 MCP 客户端测试

这些测试通过生成服务器并发送真实的 MCP 请求来验证 MCP 协议实现：

bun run test:client:mcp

单独的测试类别

# 运行 ERC20 测试
bun test src/services/erc/erc20.test.ts

# 运行 ERC721 测试
bun test src/services/erc/erc721.test.ts

# 运行 ERC1155 测试
bun test src/services/erc/erc1155.test.ts

# 运行核心工具测试
bun test src/tests/write-methods.test.ts

测试环境

测试使用 bun.setup.ts 文件来配置测试环境，包括将 Hardhat 设置为默认提供程序。

安全注意事项

• 私钥: 服务器可以将私钥存储在内存中。 使用钱包操作中的 saveToEnv 选项时请谨慎。
• API 密钥: 您的 Alchemy 和 Infura API 密钥用于连接到以太坊网络。 永远不要暴露您的 .env 文件。
• Eth Sign: ethSign 方法可以签署类似交易的数据，这不如 signMessage 安全。 谨慎使用。

贡献

欢迎贡献！ 请随时提交 Pull Request。

许可证

MIT

作者

Dennison Bertram (dennison@tally.xyz)