Bitnovo Pay

官方

用於 Bitnovo Pay 與 AI 代理整合的 MCP 伺服器。透過 Bitnovo Pay API 提供加密貨幣支付功能。功能包括建立付款、查詢狀態、生成 QR 碼，以及支援多種隧道提供者（ngrok、zrok、手動）的 Webhook 管理。

GitHub

你可以用 Bitnovo Pay MCP 做什麼？

建立鏈上加密支付 — 請您的助理使用 create_payment_onchain 為特定幣種與歐元金額生成加密貨幣地址。
建立可分享的支付連結 — 讓您的助理透過 create_payment_link 建立一個網頁支付 URL，讓客戶自行選擇加密貨幣。
查詢支付狀態 — 使用 get_payment_status 並提供支付識別碼，查詢任何支付的當前狀態與詳細資訊。
列出支援的幣種 — 使用 list_currencies_catalog 擷取可用的加密貨幣，並可依最低歐元金額進行篩選。
生成品牌支付 QR 碼 — 使用 generate_payment_qr 為現有支付產生高解析度 QR 碼。
檢視 Webhook 事件 — 使用 get_webhook_events 查詢從 Bitnovo 接收的即時支付通知。

文件

MCP Bitnovo Pay

用於 Bitnovo Pay 與 AI 代理整合的 MCP 伺服器

一個模型上下文協定 (MCP) 伺服器，透過 Bitnovo Pay API 整合，為 AI 代理提供加密貨幣支付功能。此伺服器讓 AI 模型能夠建立支付、查詢支付狀態、管理 QR 碼，以及存取加密貨幣目錄。

🚀 功能特色

8 個 MCP 工具，用於全面的支付管理：
- create_payment_onchain - 為直接支付產生加密貨幣地址
- create_payment_link - 建立包含重新導向處理的網頁支付網址
- get_payment_status - 查詢支付狀態並取得詳細資訊
- list_currencies_catalog - 取得支援的加密貨幣並可進行篩選
- generate_payment_qr - 從現有支付產生自訂 QR 碼
- get_webhook_events - 查詢即時接收的 webhook 事件
- get_webhook_url - 取得公開 webhook 網址及設定說明
- get_tunnel_status - 診斷通道連線狀態
自動化 Webhook 系統，支援 3 種通道提供者：
- 🔗 ngrok：免費的持久網址（每個帳戶 1 個靜態網域）
- 🌐 zrok：100% 免費開源，提供持久網址
- 🏢 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）
高品質 QR 碼（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（建議）

快速設定：

點擊「Deploy to Railway」或建立一個新專案
設定環境變數：
- BITNOVO_DEVICE_ID - 您的 Bitnovo 裝置 ID
- BITNOVO_BASE_URL - https://pos.bitnovo.com
部署（Railway 會自動偵測 Dockerfile）
取得您的公開網址：https://your-app.up.railway.app

連線到 claude.ai：

在「設定 → Model Context Protocol」中新增伺服器
伺服器網址：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 網址

傳輸模式偵測：

如果設定了 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`

建立一個網頁支付網址，客戶可以在其中選擇他們的加密貨幣。

使用時機：一般支付請求，未提及特定加密貨幣（預設選項）

{
  "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`

為現有支付建立自訂 QR 碼，並提供高品質輸出。

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

QR 類型：

address：僅加密貨幣地址（客戶手動輸入金額）
payment_uri：地址 + 包含金額（建議）
both：產生兩種類型（建議）
gateway_url：支付閘道網址的 QR 碼

QR 尺寸選項（v1.1.0+）：

預設：512px（針對現代顯示器最佳化）
範圍：100px - 2000px
建議尺寸：
- 512px：行動裝置和網頁顯示
- 800-1200px：標準列印
- 1600-2000px：高品質列印（海報、立架）

品質改進（v1.1.0）：

✨ QR 圖案使用 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 網址，以及用於 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 簽章驗證
重送攻擊防護 - Nonce 快取，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/

🌟 相關資源

Model Context Protocol - 官方 MCP 規範
Bitnovo Pay - 加密貨幣支付平台
Bitnovo Pay - 文件 - Bitnovo Pay 官方文件
Bitnovo Pay - 西班牙語文件 - Bitnovo Pay 官方西班牙語文件
MCP SDK - 官方 TypeScript MCP SDK