MCP Ethers 钱包

一个基于 Model Context Protocol (MCP) 的服务器，使用 ethers.js v6 提供以太坊钱包功能。

概述

MCP Ethers 钱包通过 Model Context Protocol 向 LLM 应用程序提供以太坊功能。它提供以下工具：

网络信息和管理
钱包创建和管理
交易创建和发送
合约交互（ERC20、ERC721、ERC1155）
ENS 解析
单位转换
燃料费估算
交易历史记录

该服务器遵循 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 一起使用

将 Claude Desktop 配置为使用此服务器：
- 转到设置 > Model Context Protocol
- 将命令设置为：node path/to/ethers-server/build/src/mcpServer.js
在你的 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 中：

主网网络

以太坊（ETH）
Polygon PoS（POL）
Arbitrum（ETH）
Arbitrum Nova（ETH）
Optimism（ETH）
Avalanche C-Chain（AVAX）
Base（ETH）
Polygon zkEVM（ETH）
Linea（ETH）
BNB 智能链（BNB）
Scroll（ETH）
Rari Chain 主网（ETH）
Berachain（BERA）
Sonic 主网（S）

测试网网络

Monad 测试网（MON）
MEGA 测试网（ETH）

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

自定义 RPC URL

你还可以使用自定义 RPC URL：

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

可用工具

核心网络工具

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

钱包工具

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

合约工具

getContractCode：获取合约的字节码
callContractMethod：调用合约上的只读方法
estimateGas：估算交易的燃料费

ENS 工具

lookupAddress：获取地址的 ENS 名称
resolveName：获取 ENS 名称的地址

单位转换工具

formatEther：将以 wei 为单位的值转换为以 ether 为单位的十进制字符串
parseEther：将以 ether 为单位的值转换为 wei
formatUnits：将值转换为指定单位的十进制字符串

ERC20 工具

erc20GetTokenInfo：获取代币的基本信息（名称、符号、小数位数）
erc20GetBalance：获取地址的代币余额
erc20Transfer：在账户之间转移代币
erc20GetAllowance：获取代币的批准额度
erc20Approve：批准另一个地址使用代币

ERC721 工具

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

ERC1155 工具

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

工具使用示例

获取网络信息

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

获取钱包余额

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

获取 ERC20 代币信息

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

调用合约方法

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

缓存

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

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

缓存使用生存时间（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)