ZBD MCP 服务器

为你的 LLM 添加比特币能力。

基础 SDK

此 MCP 服务器使用官方 TypeScript SDK -- https://github.com/modelcontextprotocol/typescript-sdk

前提条件

• Node.js 23+ (或 Bun/Deno/任何支持运行 .ts 文件的环境)
• Bun (用于构建可执行文件)
• 用于支付处理的 ZBD API 密钥

ZBD 设置

从 ZBD 开发者仪表板获取你的 API 密钥，并将其放入一个新的 .env 文件中，格式为 ZBD_API_KEY=XXXXXXXXXXXX (查看 .env.example 获取示例)。

完成后，运行 pnpm build 命令，并在你的客户端（例如 Claude Desktop 或 Cursor）上设置 MCP 服务器。

安装 Bun

如果你没有安装 Bun，可以使用以下方法之一进行安装：

macOS 和 Linux

# 使用 curl (推荐)
curl -fsSL https://bun.sh/install | bash

# 使用 Homebrew
brew install oven-sh/bun/bun

# 使用 npm
npm install -g bun

Windows

# 使用 PowerShell
powershell -c "irm bun.sh/install.ps1|iex"

# 使用 npm
npm install -g bun

# 使用 Scoop
scoop install bun

通过运行以下命令验证你的安装：

bun --version

安装

pnpm install

故障排除

• 使用 ps aux | grep mcp-zbd | grep -v grep 列出所有正在运行的 ZBD MCP 服务器实例。
• 使用 pkill -f mcp-zbd 杀死任何可能残留的重复 ZBD MCP 服务器实例。

项目结构

该项目演示了一种构建 MCP 工具的模块化方法：

• 每个工具都在 src 目录中的单独 TypeScript 文件中定义
• 每个工具都可以构建成 bin 目录中的独立可执行文件
• 主 index.ts 提供了实际的工具实现

可用工具

1. ZBD (src/zbd.ts): 用于全球比特币闪电支付的 ZBD API

创建新工具

要创建新工具：

1. 在 src 目录中创建一个新的 TypeScript 文件（例如，src/mytool.ts）
2. 使用现有工具作为模板
3. 将构建脚本添加到 package.json：

"build:mytool": "mkdir -p bin && bun build src/mytool.ts --compile --minify --sourcemap --outfile bin/mcp-mytool"

4. 更新 build:all 脚本以包含你的新工具

用法

构建可执行文件

# 构建所有工具
pnpm build

# 构建特定工具
pnpm build:zbd

生成的可执行文件将在 bin 目录中，可以直接运行：

./bin/mcp-zbd

Cursor 注意事项

在 Cursor 中使用这些工具时，始终使用可执行文件的完整路径：

/path/to/your/project/bin/mcp-zbd

或者，你可以直接使用 Node 运行 TypeScript 文件：

/path/to/node ~/path/to/project/src/index.ts

测试

# 运行所有测试
pnpm test

# 在观察模式下运行测试
pnpm test:watch

# 运行带有覆盖率的测试
pnpm test:coverage

ZBD.ts 可用工具

以下工具在 ZBD MCP 服务器中可用：

1. send-lightning-payment - 使用 ZBD 向闪电地址发送比特币闪电网络支付
2. send-gamertag-payment - 向 ZBD Gamertag 发送比特币支付
3. create-gamertag-charge - 为 ZBD 用户生成支付请求
4. validate-lightning-address - 验证闪电地址的有效性
5. create-lightning-charge - 为闪电地址生成支付请求
6. get-userid-by-gamertag - 从 ZBD Gamertag 检索用户 ID
7. get-gamertag-by-userid - 从用户 ID 检索 ZBD Gamertag
8. send-email-payment - 向任何电子邮件发送即时比特币支付
9. get-wallet-info - 检索有关 ZBD 项目钱包的所有数据
10. check-supported-region - 验证用户是否来自受支持的地区
11. get-zbd-ip-addresses - 获取 ZBD 服务器的官方 IP 地址
12. internal-transfer - 在两个项目之间执行资金转移
13. create-withdrawal-request - 创建比特币提款二维码
14. get-withdrawal-request - 检索有关单个提款请求的所有数据
15. send-payment - 发送比特币闪电网络支付
16. get-payment - 检索有关单个支付的所有数据
17. decode-charge - 了解 Charge 二维码的内部属性
18. create-charge - 创建新的比特币闪电网络 charge
19. get-charge - 检索有关单个 Charge 的所有数据
20. create-voucher - 创建一个可供任何 ZBD 用户兑换的单次使用 ZBD Voucher
21. get-voucher - 检索有关 ZBD Voucher 的详细信息
22. redeem-voucher - 兑换 ZBD Voucher 以将资金存入你的项目钱包
23. revoke-voucher - 撤销有效的 ZBD Voucher 并将 sats 回收到你的项目钱包
24. send-batch-lightning-payments - 在单个请求中向闪电地址发送多个比特币闪电网络支付