Bitnovo Pay

MCP Bitnovo Pay

用于将 Bitnovo Pay 集成到 AI Agent 的 MCP 服务

一个模型上下文协议（MCP）服务，通过集成 Bitnovo Pay API，为 AI Agent 提供加密货币支付功能。此服务支持 AI 模型创建支付、查询支付状态、管理二维码以及访问加密货币目录。

🚀 功能

• 8 个 MCP 工具，全面管理支付：

  • create_payment_onchain - 生成用于直接支付的加密货币地址
  • create_payment_link - 创建带有重定向处理功能的网页支付 URL
  • get_payment_status - 查询支付状态及详细信息
  • list_currencies_catalog - 获取支持的加密货币，并可进行筛选
  • generate_payment_qr - 根据现有支付生成自定义二维码
  • get_webhook_events - 实时查询收到的 webhook 事件
  • get_webhook_url - 获取公共 webhook URL 和配置说明
  • get_tunnel_status - 诊断隧道连接状态

• 自动 webhook 系统，支持 3 种隧道提供方：

  • 🔗 ngrok：免费持久 URL（每个账户 1 个静态域名）
  • 🌐 zrok：完全免费的开源方案，支持持久 URL
  • 🏢 manual：适用于具有公共 IP 的服务（N8N、Opal、VPS）

• 支持多种大模型，兼容：

  • 🤖 OpenAI ChatGPT（GPT-5、GPT-4o、Responses API、Agents SDK）
  • 🧠 Google Gemini（Gemini 2.5 Flash/Pro，2025 年 9 月、CLI、FastMCP）
  • 🔮 Claude（Claude Desktop、Claude Code）

• 高质量二维码（v1.1.0+）：

  • 📱 默认分辨率为 512px（从 300px 提升），适用于现代显示屏
  • 🖨️ 支持最高 2000px，适用于专业打印
  • ✨ 采用优化的插值算法，边缘清晰锐利
  • 🎨 自定义 Bitnovo Pay 品牌样式，支持平滑缩放徽标

• 默认保护隐私：日志中的敏感数据会被屏蔽，尽量减少数据暴露

• 安全可靠：强制使用 HTTPS、验证 HMAC 签名、安全处理密钥

• 可靠稳定：内置重试逻辑、超时处理、无状态运行

📋 前提条件

• Node.js 18+
• Bitnovo Pay 账户，需要 Device ID，可选 Device Secret
• 环境配置（请参阅下方的设置指南）

⚡ 快速开始

1. 获取 Bitnovo 凭据

1. 在 Bitnovo Pay 注册
2. 从 Bitnovo 控制面板获取你的 Device ID
3. （可选）生成 Device Secret，用于验证 webhook 签名

2. 配置 MCP 客户端

将此配置添加到 MCP 客户端配置文件中：

Claude Desktop 配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

OpenAI ChatGPT 配置（请参阅 OpenAI 设置指南）：

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

3. 重启 MCP 客户端

重启 Claude Desktop、ChatGPT 或 MCP 客户端，以加载服务。

4. 测试集成

向 AI 助手提问：“创建一笔 10 欧元的支付”

---

☁️ 云端部署（v1.2.0 新增）

MCP Bitnovo Pay 现在支持在云平台上以 HTTP 传输模式远程部署。这样一来，claude.ai 等 AI 平台便可远程连接到你的 MCP 服务。

部署到 Railway（推荐）

快速设置：

1. 点击“Deploy to Railway”或创建一个新项目
2. 设置环境变量：
   • BITNOVO_DEVICE_ID - 你的 Bitnovo 设备 ID
   • BITNOVO_BASE_URL - https://pos.bitnovo.com
3. 部署（Railway 会自动检测 Dockerfile）
4. 获取你的公开 URL：https://your-app.up.railway.app

连接到 claude.ai：

• 在“设置”→“Model Context Protocol”中添加服务
• 服务 URL：https://your-app.up.railway.app/mcp

📖 完整指南：查看 RAILWAY.md，了解详细的部署说明、故障排除和配置。

部署到 Docker

# Build the image
docker build -t mcp-bitnovo-pay .

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e PORT=3000 \
  -e BITNOVO_DEVICE_ID=your_device_id \
  -e BITNOVO_BASE_URL=https://pos.bitnovo.com \
  mcp-bitnovo-pay

部署到其他平台

该服务可运行于任何支持 Node.js 和 Docker 的平台：

• Heroku：使用环境变量推送 Dockerfile
• Fly.io：使用 fly.toml 配置部署
• Google Cloud Run：部署 Docker 容器
• AWS ECS/Fargate：使用任务定义部署

必需的环境变量：

• PORT - HTTP 端口（大多数平台会自动设置）
• BITNOVO_DEVICE_ID - 你的 Bitnovo 设备 ID
• BITNOVO_BASE_URL - Bitnovo API URL

传输模式检测：

• 如果设置了 PORT 环境变量 → HTTP 模式（远程连接）
• 如果未设置 PORT → stdio 模式（本地连接）

---

📦 安装选项

选项 A：使用 npx（推荐）

无需安装！ npx 命令会自动下载并运行最新版本。

npx -y @bitnovopay/mcp-bitnovo-pay

优点：

• ✅ 始终获取最新版本
• ✅ 无需手动更新
• ✅ 无需本地安装
• ✅ 可立即使用

选项 B：克隆仓库（用于开发）

适用于需要修改代码的贡献者或高级用户：

# Clone the repository
git clone https://github.com/bitnovo/mcp-bitnovo-pay.git
cd mcp-bitnovo-pay

# Or install from npm
npm install -g @bitnovopay/mcp-bitnovo-pay

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

优点：

• ✅ 完全掌控源代码
• ✅ 可以修改和测试变更
• ✅ 非常适合为项目作出贡献

🔧 按大模型平台配置

选择你的 AI 平台，并按照相应的设置指南操作：

Claude Desktop（Anthropic）

配置文件位置：~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 指南：Claude 设置指南

基本配置：

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

使用 Webhook（用于实时支付通知）：

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com",
        "BITNOVO_DEVICE_SECRET": "your_device_secret_hex",
        "WEBHOOK_ENABLED": "true",
        "TUNNEL_ENABLED": "true",
        "TUNNEL_PROVIDER": "ngrok",
        "NGROK_AUTHTOKEN": "your_ngrok_token",
        "NGROK_DOMAIN": "your-domain.ngrok-free.app"
      }
    }
  }
}

OpenAI ChatGPT

指南：OpenAI 设置指南 支持：GPT-5、GPT-4o、Responses API、Agents SDK

基本配置：

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

Google Gemini

指南：Gemini 设置指南 支持：Gemini 2.5 Flash/Pro（2025 年 9 月）、CLI、FastMCP

基本配置：

{
  "mcpServers": {
    "bitnovo-pay": {
      "command": "npx",
      "args": ["-y", "@bitnovopay/mcp-bitnovo-pay"],
      "env": {
        "BITNOVO_DEVICE_ID": "your_device_id_here",
        "BITNOVO_BASE_URL": "https://pos.bitnovo.com"
      }
    }
  }
}

环境变量

变量	必需	描述	示例
BITNOVO_DEVICE_ID	✅ 是	你的 Bitnovo Pay 设备标识符	12345678-abcd-1234-abcd-1234567890ab
BITNOVO_BASE_URL	✅ 是	Bitnovo API 端点	https://pos.bitnovo.com（生产环境） https://payments.pre-bnvo.com（开发环境）
BITNOVO_DEVICE_SECRET	⚠️ 可选	用于 Webhook 验证的 HMAC 密钥	your_hex_secret
WEBHOOK_ENABLED	⚠️ 可选	启用 Webhook 服务	true 或 false
TUNNEL_ENABLED	⚠️ 可选	自动启动用于 Webhook 的隧道	true 或 false
TUNNEL_PROVIDER	⚠️ 可选	隧道服务提供商	ngrok、zrok 或 manual

安全提示：切勿将凭据提交到版本控制中。请使用环境变量或安全的密钥管理方式。

🛠️ MCP 工具参考

创建支付

create_payment_onchain

创建带有指定地址的加密货币支付，用于直接交易。

适用场景：用户指定了某种加密货币（Bitcoin、ETH、USDC 等）

{
  "amount_eur": 50.0,
  "input_currency": "BTC",
  "notes": "Coffee payment"
}

create_payment_link

创建基于 Web 的支付 URL，客户可以在其中选择加密货币。

适用场景：未指定具体加密货币的一般支付请求（默认选项）

{
  "amount_eur": 50.0,
  "url_ok": "https://mystore.com/success",
  "url_ko": "https://mystore.com/cancel",
  "notes": "Order #1234"
}

支付管理

get_payment_status

获取当前付款状态及详细信息。

{
  "identifier": "payment_id_here"
}

状态码：

• NR（尚未就绪）：已创建预付款，尚未分配加密货币
• PE（待处理）：等待客户付款
• AC（等待完成）：已在内存池中检测到加密货币
• CO（已完成）：付款已在区块链上确认
• EX（已过期）：超出付款时限
• CA（已取消）：付款已取消
• FA（失败）：交易未能确认

list_currencies_catalog

获取可用的加密货币，并可按金额进行筛选。

{
  "filter_by_amount": 25.0
}

generate_payment_qr

为现有付款生成高质量的自定义二维码。

{
  "identifier": "payment_id_here",
  "qr_type": "both",
  "size": 512,
  "style": "branded"
}

二维码类型：

• address：仅包含加密货币地址（客户需手动输入金额）
• payment_uri：包含地址和金额（推荐）
• both：生成这两种类型（推荐）
• gateway_url：付款网关 URL 的二维码

二维码尺寸选项（v1.1.0+）：

• 默认值：512px（针对现代显示屏优化）
• 范围：100px - 2000px
• 推荐尺寸：
  • 512px：适用于移动设备和网页显示
  • 800-1200px：适用于标准打印
  • 1600-2000px：适用于高质量打印（海报、展架）

质量改进（v1.1.0）：

• ✨ 使用 nearest 内核插值处理二维码图案，边缘清晰锐利
• 🎯 使用 lanczos3 内核进行高质量 Logo 缩放
• 📦 PNG 压缩级别为 6，并采用自适应滤波
• 🖼️ 默认尺寸从 300px 增至 512px，提升清晰度

Webhook 工具

get_webhook_events

实时查询从 Bitnovo Pay API 接收的 webhook 事件。

启用条件：WEBHOOK_ENABLED=true

{
  "identifier": "payment_id_here",
  "limit": 50,
  "validated_only": true
}

get_webhook_url

获取公共 webhook URL，以及 Bitnovo 控制面板的配置说明。

启用条件：WEBHOOK_ENABLED=true

{
  "validate": true
}

get_tunnel_status

诊断隧道连接状态（ngrok、zrok 或手动配置）。

启用条件：WEBHOOK_ENABLED=true

{}

📚 文档

• API 工具参考 - 所有 MCP 工具的详细文档
• 使用示例 - 实际使用示例
• 错误处理 - 错误代码和故障排除
• Webhook 系统 - Webhook 配置和隧道管理

🏗️ 开发

可用脚本

npm run build        # Compile TypeScript to JavaScript
npm run dev          # Run development server with hot reload
npm start            # Start production server
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

架构

┌─────────────────┐
│   MCP Tools     │ ← 8 tools: 5 payment + 3 webhook
│ (src/tools/)    │
├─────────────────┤
│   Services      │ ← Business logic: PaymentService, CurrencyService
│ (src/services/) │
├─────────────────┤
│   API Client    │ ← Bitnovo API integration with retry logic
│ (src/api/)      │
├─────────────────┤
│ Webhook Server  │ ← HTTP Express + Event Store + Tunnel Manager
│ (src/webhook-*) │
├─────────────────┤
│   Utilities     │ ← Logging, validation, error handling, crypto
│ (src/utils/)    │
└─────────────────┘

双服务架构

MCP 服务可同时运行两个服务：

┌─────────────────────────────────────────────────────────┐
│             MCP Bitnovo Pay Server                      │
│                                                         │
│  ┌──────────────┐  ┌──────────────────┐ ┌────────────┐│
│  │ MCP Server   │  │ Webhook Server   │ │  Tunnel    ││
│  │ (stdio)      │  │ (HTTP :3000)     │ │  Manager   ││
│  └──────┬───────┘  └────────┬─────────┘ └──────┬─────┘│
│         │                   │                   │      │
│         │    Event Store    │     Public URL    │      │
│         │   (in-memory)     │   (ngrok/zrok)    │      │
│         └──────────┬────────┴──────────┬────────┘      │
└────────────────────┼───────────────────┼───────────────┘
                     │                   │
            ┌────────┴────────┐  ┌───────┴────────┐
            │                 │  │                │
       Claude Desktop   Bitnovo API    Tunnel Provider
       (MCP Tools)      (Webhooks)    (ngrok/zrok/manual)

🔒 安全

• 仅限 HTTPS - 所有 API 调用均使用 HTTPS
• HMAC 验证 - 使用 SHA-256 验证 webhook 签名
• 防重放攻击 - 使用 5 分钟 TTL 缓存 nonce
• 数据隐私 - 日志中会屏蔽敏感信息
• 不提供汇率数据 - 不公开汇率，以避免数据不准确
• 无状态设计 - 不进行本地持久化，实时查询 API
• 自动重连 - 隧道最多重试 10 次，采用指数退避
• 运行状况监控 - 每 60 秒验证一次连接

📄 许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。

🤝 贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

📞 支持

• 问题反馈：GitHub Issues
• Bitnovo 支持：https://www.bitnovo.com/
• MCP 协议：https://modelcontextprotocol.io/

🌟 相关资源

• Model Context Protocol - MCP 官方规范
• Bitnovo Pay - 加密货币支付平台
• Bitnovo Pay - Documentation - Bitnovo Pay 官方文档
• Bitnovo Pay - Documención en Español - Bitnovo Pay 官方文档（西班牙语）
• MCP SDK - TypeScript 的 MCP 官方 SDK