mcp-hd-wallet

@cryptoapis-io/mcp-hd-wallet

适用于 Crypto APIs HD Wallet（钱包即服务）产品的 MCP 服务。通过**扩展公钥（xPub/yPub/zPub）**跟踪和管理 HD 钱包——私钥绝不会离开你的设备。

**API 版本：**兼容 Crypto APIs 版本 2024-12-12

工作原理

HD（分层确定性）钱包通过单个扩展公钥（xPub）派生所有地址。将 xPub 与 Crypto APIs 同步后，该服务会代表你跟踪所有派生地址、余额和交易。

1. 同步 xPub — 提供扩展公钥（xPub、yPub 或 zPub）以开始跟踪
2. 派生地址 — 从 xPub 生成新的收款地址和找零地址
3. 查询钱包数据 — 获取余额、列出交易和 UTXO，并查看所有派生地址中的资产
4. 准备交易 — 构建未签名交易，以便使用 @cryptoapis-io/mcp-signer 在本地签名

Crypto APIs 绝不会接收或存储你的私钥。地址派生和余额跟踪仅使用扩展公钥。

功能

• 通过扩展公钥（xPub/yPub/zPub）同步钱包
• 从 xPub 派生收款地址和找零地址
• 查询所有派生地址的汇总余额、交易和资产
• 列出基于 UTXO 的钱包的 UTXO
• 直接从钱包准备未签名交易
• 支持 EVM（Ethereum、Ethereum Classic、BSC、Polygon、Avalanche（C-Chain）、Arbitrum、Base、Optimism、Tron）、UTXO（Bitcoin、Bitcoin Cash、Litecoin、Dogecoin、Dash、Zcash）和 XRP

先决条件

• Node.js 18+
• Crypto APIs 账户和 API 密钥（注册 | 获取 API 密钥）

安装

npm install @cryptoapis-io/mcp-hd-wallet

或安装所有 Crypto APIs MCP 服务：npm install @cryptoapis-io/mcp

用法

# Run with API key
npx @cryptoapis-io/mcp-hd-wallet --api-key YOUR_API_KEY

# Or use environment variable
export CRYPTOAPIS_API_KEY=YOUR_API_KEY
npx @cryptoapis-io/mcp-hd-wallet

# HTTP transport (listens on 127.0.0.1; see "Exposing the server beyond localhost")
npx @cryptoapis-io/mcp-hd-wallet --transport http --port 3000 --api-key YOUR_API_KEY

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "cryptoapis-hd-wallet": {
      "command": "npx",
      "args": ["-y", "@cryptoapis-io/mcp-hd-wallet"],
      "env": {
        "CRYPTOAPIS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "cryptoapis-hd-wallet": {
      "command": "npx",
      "args": ["-y", "@cryptoapis-io/mcp-hd-wallet"],
      "env": {
        "CRYPTOAPIS_API_KEY": "your_api_key_here"
      }
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector npx @cryptoapis-io/mcp-hd-wallet --api-key YOUR_API_KEY

n8n

1. 以 HTTP 模式启动服务：

   npx @cryptoapis-io/mcp-hd-wallet --transport http --port 3000 --api-key YOUR_API_KEY
   

2. 在 n8n 工作流中，添加一个 AI Agent 节点
3. 在 Tools 下添加一个 MCP Client Tool，并将 URL 设为 http://localhost:3000/mcp

**Docker 中的 n8n：**容器内的 localhost 并非你的计算机。使用 --host 0.0.0.0 和设置好的 MCP_AUTH_TOKEN 启动服务（参见将服务暴露到 localhost 之外），将 URL 设为 http://host.docker.internal:3000/mcp，并在 MCP Client Tool 凭据中添加 Authorization: Bearer <token> 标头。

所有服务的默认端口均为 3000。运行多个服务时，使用 --port 分配不同端口。

可用工具

manage_hd_wallet

管理 HD 钱包（同步、激活、删除、列出、查看状态）。

Action	Description
sync-wallet	通过扩展公钥（xPub/yPub/zPub）同步 HD 钱包
list-wallets	列出所有已同步的 HD 钱包
activate-wallet	激活之前同步的钱包
delete-wallet	删除已同步的钱包
get-status	获取钱包的同步状态

hd_wallet_data_utxo

查询 UTXO HD 钱包数据（Bitcoin、Bitcoin Cash、Litecoin、Dogecoin、Dash、Zcash）。

Action	Description
get-details	获取钱包余额和详情
derive-receiving-address	派生下一个收款地址
derive-change-address	派生下一个找零地址
list-addresses	列出所有派生地址
list-transactions	列出钱包交易
list-utxos	列出未花费的交易输出
list-assets	列出钱包持有的资产
prepare-transaction	从钱包准备未签名交易

hd_wallet_data_evm

查询 EVM HD 钱包数据（Ethereum、Ethereum Classic、BSC、Polygon、Avalanche（C-Chain）、Arbitrum、Base、Optimism、Tron）。

操作	描述
get-details	获取钱包余额和详情
derive-receiving-address	派生下一个收款地址
list-addresses	列出所有已派生的地址
list-transactions	列出钱包交易
list-assets	列出钱包持有的代币
prepare-transaction	准备一笔来自钱包的未签名交易

hd_wallet_data_xrp

查询 XRP HD 钱包数据。

操作	描述
get-details	获取钱包余额和详情
derive-receiving-address	派生下一个收款地址
list-addresses	列出所有已派生的地址
list-transactions	列出钱包交易
list-assets	列出钱包持有的资产

CLI 参数

参数	描述	默认值
--api-key	Crypto APIs API 密钥	CRYPTOAPIS_API_KEY 环境变量
--transport	传输类型：stdio 或 http	stdio
--host	HTTP 主机（使用 0.0.0.0 接受远程连接 — 需要通过 --api-key 提供身份验证令牌）	127.0.0.1
--auth-token	调用方必须发送的 Bearer 令牌（Authorization: Bearer <token>）；建议使用 MCP_AUTH_TOKEN 环境变量	MCP_AUTH_TOKEN 环境变量
--allowed-hosts	用逗号分隔的 Host 标头允许列表，用于非回环绑定	—
--port	HTTP 端口	3000
--path	HTTP 路径	/mcp
--stateless	启用无状态 HTTP 模式	false

HTTP API 密钥模式

使用 HTTP 传输时，服务支持两种 API 密钥模式：

• 使用 --api-key： 所有请求都使用此密钥。x-api-key 请求标头会被忽略。
• 不使用 --api-key： 每个请求都必须包含 x-api-key 标头，并提供有效的 Crypto APIs 密钥。这样可以托管公共服务，由每位用户提供自己的密钥。

# Per-request key mode (multi-tenant)
npx @cryptoapis-io/mcp-hd-wallet --transport http --port 3000
# Clients send x-api-key header with each request

将服务开放给 localhost 以外的连接

HTTP 模式默认监听 127.0.0.1，因此只有同一台机器上的进程可以访问。 若要接受来自其他机器或容器的连接，请显式绑定并保护端口：

# Startup-key mode: callers must present the token (the server refuses to start without one)
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)
npx @cryptoapis-io/mcp-hd-wallet --transport http --host 0.0.0.0 --port 3000 --api-key YOUR_API_KEY \
  --allowed-hosts mcp.internal.example
# Clients send: Authorization: Bearer $MCP_AUTH_TOKEN

# Per-request key mode: no startup key, every request must carry the caller's own x-api-key
npx @cryptoapis-io/mcp-hd-wallet --transport http --host 0.0.0.0 --port 3000

未绑定到回环地址时，--allowed-hosts 会限制 Host 标头（防止 DNS 重绑定）。建议使用 MCP_AUTH_TOKEN，而不是 --auth-token：命令行参数会显示在进程列表中。

Stdio 传输始终要求在启动时提供 API 密钥。

重要：需要 API 密钥

警告： 使用无效 API 密钥或不提供有效 API 密钥发起请求，可能会导致你的 IP 被 Crypto APIs 生态系统封禁。启动任何服务前，请务必确保已配置有效的 API 密钥。

远程 MCP 服务

Crypto APIs 提供官方远程 MCP 服务，可通过 HTTP Streamable 传输使用所有工具，地址为 https://ai.cryptoapis.io/mcp。通过 x-api-key 标头传递 API 密钥 — 无需安装。

许可证

MIT