Bitnovo Pay

官方

用于Bitnovo Pay与AI代理集成的MCP服务器。通过Bitnovo Pay API提供加密货币支付功能。功能包括支付创建、状态查询、二维码生成以及支持多种隧道提供商（ngrok、zrok、手动）的webhook管理。

GitHub

你可以用 Bitnovo Pay MCP 做什么？

创建链上加密支付 — 让您的助手为特定币种和欧元金额生成加密货币地址，使用 create_payment_onchain。
创建可分享的支付链接 — 让您的助手构建一个网页支付 URL，客户可在其中选择加密货币，使用 create_payment_link。
检查支付状态 — 使用其标识符请求任何支付的当前状态和详细信息，使用 get_payment_status。
列出支持的货币 — 检索可用的加密货币，可选择按最低欧元金额过滤，使用 list_currencies_catalog。
生成品牌支付二维码 — 为现有支付生成高分辨率二维码，使用 generate_payment_qr。
检查 Webhook 事件 — 查询从 Bitnovo 接收的实时支付通知，使用 get_webhook_events。

文档

MCP Bitnovo Pay

用于 AI 代理集成 Bitnovo Pay 的 MCP 服务器

一个模型上下文协议 (MCP) 服务器，通过 Bitnovo Pay API 集成为 AI 代理提供加密货币支付能力。该服务器使 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：100% 免费开源，提供持久 URL
- 🏢 manual：适用于具有公网 IP 的服务器（N8N、Opal、VPS）
多 LLM 支持 - 兼容：
- 🤖 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 账户，包含设备 ID 和可选的设备密钥
环境配置（请参阅下方的设置指南）

⚡ 快速开始

1. 获取您的 Bitnovo 凭证

在 Bitnovo Pay 注册
从 Bitnovo 仪表板获取您的设备 ID
（可选）生成一个设备密钥用于 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（推荐）

快速设置：

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

连接到 claude.ai：

在“设置” → “模型上下文协议”中添加服务器
服务器 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

优势：

✅ 完全控制源代码
✅ 能够修改和测试更改
✅ 非常适合为项目做贡献

🔧 按 LLM 平台配置

选择您的 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"
      }
    }
  }
}

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

{
  "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`	⚠️ 可选	为 Webhooks 自动启动隧道	`true` 或 `false`
`TUNNEL_PROVIDER`	⚠️ 可选	隧道提供商	`ngrok`、`zrok` 或 `manual`

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

🛠️ MCP 工具参考

支付创建

`create_payment_onchain`

创建一个加密货币支付，并生成一个用于直接交易的特定地址。

使用场景：用户指定了一种加密货币（比特币、ETH、USDC 等）

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

`create_payment_link`

创建一个基于网页的支付 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 内核实现高质量徽标缩放
📦 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 或 manual）。

可用条件：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 签名验证
重放攻击防护 - 随机数缓存，TTL 为 5 分钟
数据隐私 - 日志中的敏感信息被遮蔽
无汇率数据 - 不暴露汇率以防止不准确
无状态设计 - 无本地持久化，实时 API 查询
自动重连 - 隧道指数退避重试，最多 10 次
健康监控 - 每 60 秒验证一次连接

📄 许可证

本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

🤝 贡献

Fork 本仓库
创建您的功能分支（git checkout -b feature/amazing-feature）
提交您的更改（git commit -m 'Add amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开一个 Pull Request

📞 支持

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

🌟 相关资源

模型上下文协议 - 官方 MCP 规范
Bitnovo Pay - 加密货币支付平台
Bitnovo Pay - 文档 - Bitnovo Pay 官方文档
Bitnovo Pay - 西班牙语文档 - Bitnovo Pay 官方西班牙语文档
MCP SDK - 官方 TypeScript MCP SDK