Bitnovo Pay

chính thức

Máy chủ MCP để tích hợp Bitnovo Pay với các tác nhân AI. Cung cấp khả năng thanh toán tiền điện tử thông qua API Bitnovo Pay. Các tính năng bao gồm tạo thanh toán, kiểm tra trạng thái, tạo mã QR và quản lý webhook với hỗ trợ nhiều nhà cung cấp tunnel (ngrok, zrok, thủ công).

GitHub

Bạn có thể làm gì với Bitnovo Pay MCP?

Tạo một khoản thanh toán on-chain bằng tiền điện tử — Yêu cầu trợ lý của bạn tạo một địa chỉ tiền điện tử cho một loại coin và số tiền euro cụ thể bằng create_payment_onchain.
Tạo một liên kết thanh toán có thể chia sẻ — Nhờ trợ lý xây dựng một URL thanh toán trên web, nơi khách hàng chọn loại tiền điện tử của họ qua create_payment_link.
Kiểm tra trạng thái thanh toán — Yêu cầu trạng thái hiện tại và chi tiết của bất kỳ khoản thanh toán nào bằng mã định danh của nó qua get_payment_status.
Liệt kê các loại tiền tệ được hỗ trợ — Truy xuất các loại tiền điện tử khả dụng, tùy chọn được lọc theo số tiền euro tối thiểu, bằng list_currencies_catalog.
Tạo mã QR thanh toán có thương hiệu — Tạo mã QR độ phân giải cao cho một khoản thanh toán hiện có bằng generate_payment_qr.
Kiểm tra sự kiện webhook — Truy vấn các thông báo thanh toán thời gian thực nhận được từ Bitnovo qua get_webhook_events.

Tài liệu

MCP Bitnovo Pay

Máy chủ MCP cho tích hợp Bitnovo Pay với các tác nhân AI

Máy chủ Model Context Protocol (MCP) cung cấp cho các tác nhân AI khả năng thanh toán tiền điện tử thông qua tích hợp API Bitnovo Pay. Máy chủ này cho phép các mô hình AI tạo thanh toán, kiểm tra trạng thái thanh toán, quản lý mã QR và truy cập danh mục tiền điện tử.

🚀 Tính năng

8 Công cụ MCP để quản lý thanh toán toàn diện:
- create_payment_onchain - Tạo địa chỉ tiền điện tử cho thanh toán trực tiếp
- create_payment_link - Tạo URL thanh toán web với xử lý chuyển hướng
- get_payment_status - Truy vấn trạng thái thanh toán với thông tin chi tiết
- list_currencies_catalog - Lấy danh sách tiền điện tử được hỗ trợ với bộ lọc
- generate_payment_qr - Tạo mã QR tùy chỉnh từ các thanh toán hiện có
- get_webhook_events - Truy vấn sự kiện webhook nhận được theo thời gian thực
- get_webhook_url - Lấy URL webhook công khai với hướng dẫn cấu hình
- get_tunnel_status - Chẩn đoán trạng thái kết nối đường hầm
Hệ thống Webhook Tự động với 3 nhà cung cấp đường hầm:
- 🔗 ngrok: URL cố định miễn phí (1 tên miền tĩnh mỗi tài khoản)
- 🌐 zrok: Mã nguồn mở 100% miễn phí với URL cố định
- 🏢 thủ công: Dành cho máy chủ có IP công khai (N8N, Opal, VPS)
Hỗ trợ Đa LLM - Tương thích với:
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, API Phản hồi, SDK Tác nhân)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Tháng 9/2025, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
Mã QR Chất lượng Cao (v1.1.0+):
- 📱 Độ phân giải mặc định 512px (tăng từ 300px) cho màn hình hiện đại
- 🖨️ Hỗ trợ lên đến 2000px cho in ấn chuyên nghiệp
- ✨ Cạnh sắc nét với thuật toán nội suy tối ưu
- 🎨 Thương hiệu Bitnovo Pay tùy chỉnh với tỷ lệ logo mượt mà
Quyền riêng tư Mặc định - Dữ liệu nhạy cảm được che trong nhật ký, tiết lộ dữ liệu tối thiểu
Bảo mật - Thực thi HTTPS, xác thực chữ ký HMAC, xử lý bí mật an toàn
Đáng tin cậy - Logic thử lại tích hợp, xử lý thời gian chờ, hoạt động không trạng thái

📋 Điều kiện tiên quyết

Node.js 18+
Tài khoản Bitnovo Pay với ID Thiết bị và Bí mật Thiết bị tùy chọn
Cấu hình Môi trường (xem hướng dẫn thiết lập bên dưới)

⚡ Bắt đầu Nhanh

1. Lấy Thông tin Xác thực Bitnovo

Đăng ký tại Bitnovo Pay
Lấy ID Thiết bị từ bảng điều khiển Bitnovo
(Tùy chọn) Tạo Bí mật Thiết bị để xác thực chữ ký webhook

2. Cấu hình Máy khách MCP

Thêm cấu hình này vào tệp cấu hình máy khách MCP của bạn:

Dành cho 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"
      }
    }
  }
}

Dành cho OpenAI ChatGPT (xem Hướng dẫn Thiết lập 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. Khởi động lại Máy khách MCP

Khởi động lại Claude Desktop, ChatGPT hoặc máy khách MCP của bạn để tải máy chủ.

4. Kiểm tra Tích hợp

Hỏi trợ lý AI của bạn: "Tạo một khoản thanh toán 10 euro"

☁️ Triển khai Đám mây (MỚI trong v1.2.0)

MCP Bitnovo Pay hiện hỗ trợ triển khai từ xa trên các nền tảng đám mây với chế độ truyền tải HTTP. Điều này cho phép các nền tảng AI như claude.ai kết nối từ xa với máy chủ MCP của bạn.

Triển khai lên Railway (Khuyến nghị)

Thiết lập Nhanh:

Nhấp "Triển khai lên Railway" hoặc tạo dự án mới
Đặt biến môi trường:
- BITNOVO_DEVICE_ID - ID thiết bị Bitnovo của bạn
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Triển khai (Railway tự động phát hiện Dockerfile)
Lấy URL công khai của bạn: https://your-app.up.railway.app

Kết nối với claude.ai:

Thêm máy chủ trong Cài đặt → Model Context Protocol
URL Máy chủ: https://your-app.up.railway.app/mcp

📖 Hướng dẫn Đầy đủ: Xem RAILWAY.md để biết hướng dẫn triển khai chi tiết, khắc phục sự cố và cấu hình.

Triển khai lên 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

Triển khai lên Nền tảng Khác

Máy chủ hoạt động trên mọi nền tảng hỗ trợ Node.js và Docker:

Heroku: Đẩy Dockerfile với biến môi trường
Fly.io: Triển khai với cấu hình fly.toml
Google Cloud Run: Triển khai container Docker
AWS ECS/Fargate: Triển khai với định nghĩa tác vụ

Biến Môi trường Bắt buộc:

PORT - Cổng HTTP (tự động đặt bởi hầu hết nền tảng)
BITNOVO_DEVICE_ID - ID thiết bị Bitnovo của bạn
BITNOVO_BASE_URL - URL API Bitnovo

Phát hiện Chế độ Truyền tải:

Nếu biến môi trường PORT được đặt → Chế độ HTTP (kết nối từ xa)
Nếu không có PORT → Chế độ stdio (kết nối cục bộ)

📦 Tùy chọn Cài đặt

Tùy chọn A: Sử dụng npx (Khuyến nghị)

Không cần cài đặt! Lệnh npx tự động tải xuống và chạy phiên bản mới nhất.

npx -y @bitnovopay/mcp-bitnovo-pay

Ưu điểm:

✅ Luôn nhận phiên bản mới nhất
✅ Không cần cập nhật thủ công
✅ Không cần cài đặt cục bộ
✅ Hoạt động ngay lập tức

Tùy chọn B: Sao chép Kho lưu trữ (Dành cho Phát triển)

Dành cho người đóng góp hoặc người dùng nâng cao cần sửa đổi mã:

# 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

Ưu điểm:

✅ Toàn quyền kiểm soát mã nguồn
✅ Khả năng sửa đổi và kiểm tra thay đổi
✅ Lý tưởng để đóng góp cho dự án

🔧 Cấu hình theo Nền tảng LLM

Chọn nền tảng AI của bạn và làm theo hướng dẫn thiết lập cụ thể:

Claude Desktop (Anthropic)

Vị trí Tệp Cấu hình: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Hướng dẫn: Hướng dẫn Thiết lập Claude

Cấu hình Cơ bản:

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

Với Webhooks (cho thông báo thanh toán thời gian thực):

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

Hướng dẫn: Hướng dẫn Thiết lập OpenAI Hỗ trợ: GPT-5, GPT-4o, API Phản hồi, SDK Tác nhân

Cấu hình Cơ bản:

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

Hướng dẫn: Hướng dẫn Thiết lập Gemini Hỗ trợ: Gemini 2.5 Flash/Pro (Tháng 9/2025), CLI, FastMCP

Cấu hình Cơ bản:

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

Biến Môi trường

Biến	Bắt buộc	Mô tả	Ví dụ
`BITNOVO_DEVICE_ID`	✅ Có	Định danh thiết bị Bitnovo Pay của bạn	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ Có	Điểm cuối API Bitnovo	`https://pos.bitnovo.com` (sản xuất) `https://payments.pre-bnvo.com` (phát triển)
`BITNOVO_DEVICE_SECRET`	⚠️ Tùy chọn	Bí mật HMAC để xác thực webhook	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ Tùy chọn	Kích hoạt máy chủ webhook	`true` hoặc `false`
`TUNNEL_ENABLED`	⚠️ Tùy chọn	Tự động khởi động đường hầm cho webhooks	`true` hoặc `false`
`TUNNEL_PROVIDER`	⚠️ Tùy chọn	Nhà cung cấp đường hầm	`ngrok`, `zrok`, hoặc `manual`

Lưu ý Bảo mật: Không bao giờ commit thông tin xác thực vào kiểm soát phiên bản. Sử dụng biến môi trường hoặc quản lý bí mật an toàn.

🛠️ Tham khảo Công cụ MCP

Tạo Thanh toán

`create_payment_onchain`

Tạo thanh toán tiền điện tử với địa chỉ cụ thể cho giao dịch trực tiếp.

Sử dụng khi: Người dùng chỉ định tiền điện tử (Bitcoin, ETH, USDC, v.v.)

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

`create_payment_link`

Tạo URL thanh toán dựa trên web nơi khách hàng có thể chọn tiền điện tử của họ.

Sử dụng khi: Yêu cầu thanh toán chung chung không đề cập tiền điện tử cụ thể (TÙY CHỌN MẶC ĐỊNH)

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

Quản lý Thanh toán

`get_payment_status`

Truy xuất trạng thái thanh toán hiện tại với thông tin chi tiết.

{
  "identifier": "payment_id_here"
}

Mã Trạng thái:

NR (Chưa Sẵn sàng): Thanh toán trước được tạo, chưa gán tiền điện tử
PE (Đang chờ): Đợi khách hàng thanh toán
AC (Đợi Hoàn tất): Phát hiện tiền điện tử trong mempool
CO (Hoàn tất): Thanh toán được xác nhận trên blockchain
EX (Hết hạn): Vượt quá giới hạn thời gian thanh toán
CA (Đã hủy): Thanh toán bị hủy
FA (Thất bại): Giao dịch không xác nhận được

`list_currencies_catalog`

Lấy danh sách tiền điện tử khả dụng với bộ lọc dựa trên số tiền tùy chọn.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

Tạo mã QR tùy chỉnh cho các thanh toán hiện có với đầu ra chất lượng cao.

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

Loại QR:

address: Chỉ địa chỉ tiền điện tử (khách hàng tự nhập số tiền)
payment_uri: Địa chỉ + số tiền (khuyến nghị)
both: Tạo cả hai loại (khuyến nghị)
gateway_url: QR của URL cổng thanh toán

Tùy chọn Kích thước QR (v1.1.0+):

Mặc định: 512px (tối ưu cho màn hình hiện đại)
Phạm vi: 100px - 2000px
Kích thước khuyến nghị:
- 512px: Hiển thị di động và web
- 800-1200px: In ấn tiêu chuẩn
- 1600-2000px: In ấn chất lượng cao (áp phích, giá đỡ)

Cải tiến Chất lượng (v1.1.0):

✨ Cạnh sắc nét với nội suy kernel nearest cho mẫu QR
🎯 Tỷ lệ logo chất lượng cao với kernel lanczos3
📦 Mức nén PNG 6 với lọc thích ứng
🖼️ Kích thước mặc định tăng từ 300px lên 512px để rõ ràng hơn

Công cụ Webhook

`get_webhook_events`

Truy vấn sự kiện webhook nhận được theo thời gian thực từ API Bitnovo Pay.

Khả dụng khi: WEBHOOK_ENABLED=true

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

`get_webhook_url`

Lấy URL webhook công khai với hướng dẫn cấu hình cho bảng điều khiển Bitnovo.

Khả dụng khi: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Chẩn đoán trạng thái kết nối đường hầm (ngrok, zrok, hoặc thủ công).

Khả dụng khi: WEBHOOK_ENABLED=true

{}

📚 Tài liệu

Tham khảo Công cụ API - Tài liệu chi tiết cho tất cả công cụ MCP
Ví dụ Sử dụng - Ví dụ sử dụng thực tế
Xử lý Lỗi - Mã lỗi và khắc phục sự cố
Hệ thống Webhook - Cấu hình webhook và quản lý đường hầm

🏗️ Phát triển

Tập lệnh Khả dụng

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

Kiến trúc

┌─────────────────┐
│   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/)    │
└─────────────────┘

Kiến trúc Máy chủ Kép

Máy chủ MCP có thể chạy hai máy chủ đồng thời:

┌─────────────────────────────────────────────────────────┐
│             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)

🔒 Bảo mật

Chỉ HTTPS - Tất cả cuộc gọi API sử dụng HTTPS
Xác thực HMAC - Xác minh chữ ký webhook với SHA-256
Ngăn chặn Tấn công Phát lại - Bộ nhớ đệm nonce với TTL 5 phút
Quyền riêng tư Dữ liệu - Thông tin nhạy cảm được che trong nhật ký
Không Dữ liệu Tỷ giá - Tỷ giá hối đoái không được tiết lộ để tránh sai lệch
Thiết kế Không Trạng thái - Không lưu trữ cục bộ, truy vấn API thời gian thực
Tự động Kết nối lại - Lùi theo cấp số nhân lên đến 10 lần thử cho đường hầm
Giám sát Tình trạng - Xác minh kết nối mỗi 60 giây

📄 Giấy phép

Dự án này được cấp phép theo Giấy phép MIT - xem tệp LICENSE để biết chi tiết.

🤝 Đóng góp

Fork kho lưu trữ
Tạo nhánh tính năng của bạn (git checkout -b feature/amazing-feature)
Commit thay đổi của bạn (git commit -m 'Add amazing feature')
Đẩy lên nhánh (git push origin feature/amazing-feature)
Mở Yêu cầu Kéo (Pull Request)

📞 Hỗ trợ

Vấn đề: GitHub Issues
Hỗ trợ Bitnovo: https://www.bitnovo.com/
Giao thức MCP: https://modelcontextprotocol.io/

🌟 Liên quan

Model Context Protocol - Đặc tả MCP chính thức
Bitnovo Pay - Nền tảng thanh toán tiền điện tử
Bitnovo Pay - Tài liệu - Tài liệu Chính thức Bitnovo Pay
Bitnovo Pay - Tài liệu tiếng Tây Ban Nha - Tài liệu Chính thức Bitnovo Pay
MCP SDK - SDK MCP chính thức cho TypeScript