Botwallet MCP

---

在 MCP 客户端配置中添加一个 JSON 块即可。

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

然后告诉你的 Agent：“为自己创建一个 Botwallet。”

它会运行 botwallet_register，在本地生成一个加密密钥份额，然后返回一个存款地址。无需预先进行设置，也无需配置 API 密钥。

之后可以这样说：

“向 @acme-bot 发送 $5，获取数据报告”

如果金额在保护规则范围内，Agent 就会签署并提交交易。否则，它会请求所有者批准。

“为咨询服务创建一张 $25 的发票”

Agent 会创建一个付款链接。有人付款后，USDC 会直接进入钱包。

“找一个语音转文本 API 并使用它”

Agent 会搜索 x402 目录，找到一个付费 API，支付使用费用并返回结果。

签名的工作原理

每个钱包都使用 FROST 2-of-2 阈值签名。创建钱包时，密钥生成仪式会生成两个份额：

• 密钥 1 — Agent 的份额，存储在本地的 ~/.botwallet/seeds/
• 密钥 2 — 服务端的份额，由 Botwallet 保管

完整私钥从不会存在。每笔交易都需要双方共同签名。Agent 和 Botwallet 都无法单独转移资金。所有者可以设置消费限额，并批准任何超出规则的操作。

Botwallet 会准备每笔交易；在密钥 1 共同签名前，本服务会解码交易，并拒绝签署任何不符合以下条件的交易：只能将 USDC 转出钱包，金额必须是约定的金额并转入收款人关联的（标准）USDC 账户，手续费不得超过报价金额（付费 API 的手续费以整美分报价，最多可高出 1 美分），且不得包含其他操作。对于提现、付费 API 以及向 Solana 地址付款，系统会将收款人地址与 Agent 提供的地址进行核对。对于向用户名付款，地址由 Botwallet 查询得出，因此系统只会核对金额和手续费是否符合 Agent 的请求。Agent CLI 和签名页面也采用相同规则。

Agent 自己提供的金额、收款人和手续费会保存在内存中，因此只有在启动转账的 MCP 服务进程仍在运行时才会使用这些信息。服务重启后（所有者可能数小时后才批准，因此这种情况很常见），密钥 1 会根据 Botwallet 记录的金额、收款人和手续费检查交易，并且绝不会签署超过固定上限的手续费。

如果付款调用超时或连接中断，结果会说明资金是否可能已转出。OUTCOME_UNKNOWN 表示应先检查其 check_tool 中指定的工具（通常是 botwallet_list_payments 或 botwallet_get_withdrawal；如果 Botwallet 将转账列为失败但资金仍可能已转出，则检查 botwallet_balance），再尝试付款；若要重试同一笔付款，请传回其 idempotency_key。

待处理、冻结和重复付款

已发送，尚未确认。 Botwallet 会等待 Solana 确认付款或提现。如果网络未能及时确认，工具会返回正常结果，而非错误，其中包含 status: "pending"、sent: true、Solana 签名、区块浏览器链接和 check_tool。交易仍有可能成功，因此 Agent 不得再次付款：约一分钟后，check_tool 中的工具会显示 completed 或 failed。

钱包已冻结。 所有者可以在 Botwallet 控制面板中冻结钱包。被冻结的钱包仍可收款，但不能付款：新付款、提现和付费 API 调用都会被阻止；确认操作会在签名或发送任何内容之前以 WALLET_SUSPENDED 终止。冻结前已批准的转账会保留：所有者解除冻结后，Agent 可使用相同的确认工具和 transaction_id 完成转账（对于付费 API，使用相同的 fetch_id 调用 botwallet_x402_pay_and_fetch）。

重试请求。 botwallet_pay 和 botwallet_withdraw 会返回 idempotency_key。再次使用该密钥调用工具，会返回首次请求的处理结果，而不会再次发起付款。如果没有提供密钥，系统会生成一个新密钥，因此该调用会发起一笔新付款。已用于其他类型请求的密钥，或仍在创建中的密钥，会返回 IDEMPOTENCY_KEY_CONFLICT。

安装

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Claude Code

claude mcp add botwallet -- npx -y @botwallet/mcp

这会将其添加到当前项目中。若要在每个项目中都使用，请添加 --scope user：

claude mcp add --scope user botwallet -- npx -y @botwallet/mcp

在原生 Windows（非 WSL）上，npx 需要使用 cmd /c 包装：claude mcp add botwallet -- cmd /c npx -y @botwallet/mcp。

Cursor

前往 Settings > MCP，点击 Add new MCP server，然后添加：

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Cline

打开 Cline 侧边栏，点击 MCP Servers，然后点击 Configure 并添加：

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

其他 MCP 客户端

所有客户端的配置都相同——将 npx -y @botwallet/mcp 作为命令。

全局安装（替代方案）

npm install -g @botwallet/mcp

如果选择全局安装，请使用 botwallet-mcp 作为命令，而非 npx -y @botwallet/mcp。

环境变量

变量	默认值	用途
BOTWALLET_API_KEY	—	API 密钥（与 CLI 一样，也支持 BW_API_KEY）。设置后，该变量会决定使用哪个钱包。仅凭此变量即可进行只读操作；付款、提现和付费 API 调用还需要该钱包的密钥份额（Key 1），存放在 ~/.botwallet/seeds/<wallet>.seed 中。签名时会使用 config.json 中配置了此密钥的钱包；如果该钱包不在 config.json 中，请将 BOTWALLET_WALLET 设置为种子文件的名称
BOTWALLET_WALLET	—	要使用的钱包（如果有多个）。如果没有钱包使用此名称，服务将无法启动。仅适用于 MCP：CLI 使用 --wallet
BOTWALLET_API_URL	https://api.botwallet.co/v1	API 端点，与 CLI 读取的变量相同。旧版本使用的 BOTWALLET_BASE_URL 仍然有效。如果两者都未设置，则会像 CLI 一样使用 ~/.botwallet/config.json 中的 base_url

这些变量均为可选项。服务会读取 ~/.botwallet/config.json（与 CLI 共用）并确定其余配置。不设置这些变量时，服务会使用默认钱包；注册或导入钱包后，该钱包会成为默认钱包。

工具

8 个分组，共 36 个工具。

钱包管理

工具	功能说明
botwallet_ping	检查 API 连通性
botwallet_register	创建新钱包（FROST 密钥生成）
botwallet_info	钱包元数据和状态
botwallet_balance	链上余额和剩余预算
botwallet_update_owner	设置所有者邮箱
botwallet_rename	更改显示名称
botwallet_wallet_list	列出本地钱包
botwallet_wallet_use	切换活动钱包

付款

工具	功能说明
botwallet_lookup	检查收款方是否存在
botwallet_can_i_afford	付款前检查
botwallet_pay	向他人付款（在限额内时自动签名）
botwallet_confirm_payment	所有者批准后完成付款
botwallet_list_payments	列出转出付款
botwallet_cancel_payment	取消待处理的付款

收款

工具	功能说明
botwallet_create_paylink	创建付款请求或发票
botwallet_send_paylink	通过电子邮件或机器人收件箱发送付款链接
botwallet_get_paylink	检查付款链接状态
botwallet_list_paylinks	列出你的付款链接
botwallet_cancel_paylink	取消待处理的付款链接

资金存入

工具	功能说明
botwallet_get_deposit_address	获取 USDC 存款地址
botwallet_request_funds	向人类所有者请求资金
botwallet_list_fund_requests	列出过去的资金请求

提现

工具	功能说明
botwallet_withdraw	将 USDC 提现到外部 Solana 地址
botwallet_confirm_withdrawal	批准后完成提现
botwallet_get_withdrawal	检查提现状态

x402 付费 API

工具	功能说明
botwallet_x402_discover	搜索付费 API
botwallet_x402_fetch	探测 URL 以了解付款要求
botwallet_x402_pay_and_fetch	付款并从 x402 API 获取内容

历史记录和安全限制

工具	功能说明
botwallet_transactions	完整交易账本
botwallet_my_limits	查看所有者设置的支出限额
botwallet_pending_approvals	列出等待批准的操作
botwallet_approval_status	检查特定审批
botwallet_events	钱包通知

钱包转移

工具	功能说明
botwallet_wallet_export	将钱包导出为加密的 .bwlt 文件（可在 24 小时内导入，最多导入 5 次）
botwallet_wallet_import	从 .bwlt 文件导入钱包，并使用新的本地名称
botwallet_wallet_backup	显示密钥 1（12 个单词）以供所有者备份，分两次调用并使用一次性代码

资源

URI	返回内容
botwallet://status	钱包摘要——余额、预算、种子文件状态，以及在尚无所有者认领钱包时显示的认领链接

架构

┌─────────────────┐     stdio (JSON-RPC)     ┌──────────────────┐
│   AI Client     │◄────────────────────────►│  Botwallet MCP   │
│ (Claude/Cursor) │                          │     Server       │
└─────────────────┘                          └────────┬─────────┘
                                                      │
                                              ┌───────┴───────┐
                                              │               │
                                     ~/.botwallet/     api.botwallet.co
                                     (seeds, config)        (API)
                                                              │
                                                        ┌─────┴─────┐
                                                        │  Solana   │
                                                        │ (mainnet) │
                                                        └───────────┘

服务在 Agent 的机器上本地运行。密钥份额存储在 ~/.botwallet/seeds/ 中，绝不会发送给 Botwallet。服务会与 Botwallet API 通信以进行联合签名，并将组合后的签名提交到 Solana。

安全

Agent 无法绕过消费限额。这些限额由服务器端强制执行。超过自动批准阈值的交易会提交给所有者审批。系统中的任何位置都不会存储完整私钥。

每个工具都带有 MCP 工具注解。余额、历史记录和查询工具被标记为只读，因此支持注解的客户端可以直接运行，无需询问。转移资金的工具（botwallet_pay、botwallet_withdraw、确认工具、botwallet_x402_pay_and_fetch）、操作 Key 1 的工具（botwallet_wallet_backup、botwallet_wallet_export、botwallet_wallet_import）以及更改所有者的工具都被标记为破坏性操作，因此客户端可以继续在执行前询问。只允许只读工具，比对整个服务选择“始终允许”更安全。

Key 1（Agent 的密钥份额）仅存储在 Agent 的设备上，绝不会发送给 Botwallet。注册时，API 密钥会保存到 ~/.botwallet/config.json，不会显示出来。有两种操作会显示密钥材料，因此只有在所有者要求时才使用：

• botwallet_wallet_backup 会向 Agent 显示 Key 1（12 个单词），以便 Agent 将其交给所有者；所有者需要这些单词才能提款和恢复钱包。随后，这些单词会留在 AI 对话中，因此应将该对话视为敏感信息。与 CLI 一样，需要调用两次：第一次返回一个有效期为 30 秒的一次性代码，第二次提供该代码后才会显示这些单词。这可以防止意外泄露 Key 1，但无法阻止蓄意泄露它的 Agent。
• botwallet_wallet_export 会写入一个包含 Key 1 和 API 密钥的 .bwlt 文件。任何持有该文件的人都可以在 24 小时内导入钱包。

有关漏洞报告，请参阅 SECURITY.md。

CLI 互操作

此 MCP 服务与 Botwallet CLI 共用相同的本地文件：

• 配置：~/.botwallet/config.json
• 种子：~/.botwallet/seeds/*.seed
• 导出格式：.bwlt（加密，支持双向使用；包含 Key 1 和 API 密钥，请妥善保密）

使用 CLI 创建的钱包可在 MCP 服务中使用，反之亦然。

开发

git clone https://github.com/botwallet-co/mcp.git
cd mcp
npm install
npm run build
npm test                # unit + integration tests, offline
npm run test:e2e        # E2E tests against the live API (no payments)
npm run inspect         # Open in MCP Inspector

许可证

Apache 2.0