MCP Bitnovo Pay
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Bitnovo Pay create a payment for 25 euros"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Bitnovo Pay
MCP server for Bitnovo Pay integration with AI agents
A Model Context Protocol (MCP) server that provides AI agents with cryptocurrency payment capabilities through Bitnovo Pay API integration. This server enables AI models to create payments, check payment status, manage QR codes, and access cryptocurrency catalogs.
๐ Features
8 MCP Tools for comprehensive payment management:
create_payment_onchain- Generate cryptocurrency addresses for direct paymentscreate_payment_link- Create web payment URLs with redirect handlingget_payment_status- Query payment status with detailed informationlist_currencies_catalog- Get supported cryptocurrencies with filteringgenerate_payment_qr- Generate custom QR codes from existing paymentsget_webhook_events- Query webhook events received in real-timeget_webhook_url- Get public webhook URL with configuration instructionsget_tunnel_status- Diagnose tunnel connection status
Automatic Webhook System with 3 tunnel providers:
๐ ngrok: Free persistent URL (1 static domain per account)
๐ zrok: 100% free open-source with persistent URLs
๐ข manual: For servers with public IP (N8N, Opal, VPS)
Multi-LLM Support - Compatible with:
๐ค OpenAI ChatGPT (GPT-5, GPT-4o, Responses API, Agents SDK)
๐ง Google Gemini (Gemini 2.5 Flash/Pro Sept 2025, CLI, FastMCP)
๐ฎ Claude (Claude Desktop, Claude Code)
High-Quality QR Codes (v1.1.0+):
๐ฑ 512px default resolution (up from 300px) for modern displays
๐จ๏ธ Support up to 2000px for professional printing
โจ Sharp edges with optimized interpolation algorithms
๐จ Custom Bitnovo Pay branding with smooth logo scaling
Privacy by Default - Sensitive data masked in logs, minimal data exposure
Secure - HTTPS enforcement, HMAC signature validation, secure secret handling
Reliable - Built-in retry logic, timeout handling, stateless operation
Related MCP server: Bit2Me MCP Server
๐ Prerequisites
Node.js 18+
Bitnovo Pay Account with Device ID and optional Device Secret
Environment Configuration (see setup guides below)
โก Quick Start
1. Get Your Bitnovo Credentials
Sign up at Bitnovo Pay
Obtain your Device ID from the Bitnovo dashboard
(Optional) Generate a Device Secret for webhook signature validation
2. Configure Your MCP Client
Add this configuration to your MCP client config file:
For 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"
}
}
}
}For OpenAI ChatGPT (see OpenAI Setup Guide):
{
"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. Restart Your MCP Client
Restart Claude Desktop, ChatGPT, or your MCP client to load the server.
4. Test the Integration
Ask your AI assistant: "Create a payment for 10 euros"
โ๏ธ Cloud Deployment (NEW in v1.2.0)
MCP Bitnovo Pay now supports remote deployment on cloud platforms with HTTP transport mode. This enables AI platforms like claude.ai to connect to your MCP server remotely.
Deploy to Railway (Recommended)
Quick Setup:
Click "Deploy to Railway" or create a new project
Set environment variables:
BITNOVO_DEVICE_ID- Your Bitnovo device IDBITNOVO_BASE_URL-https://pos.bitnovo.com
Deploy (Railway auto-detects Dockerfile)
Get your public URL:
https://your-app.up.railway.app
Connect to claude.ai:
Add server in Settings โ Model Context Protocol
Server URL:
https://your-app.up.railway.app/mcp
๐ Full Guide: See RAILWAY.md for detailed deployment instructions, troubleshooting, and configuration.
Deploy to 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-payDeploy to Other Platforms
The server works on any platform that supports Node.js and Docker:
Heroku: Push Dockerfile with environment variables
Fly.io: Deploy with
fly.tomlconfigurationGoogle Cloud Run: Deploy Docker container
AWS ECS/Fargate: Deploy with task definition
Required Environment Variables:
PORT- HTTP port (auto-set by most platforms)BITNOVO_DEVICE_ID- Your Bitnovo device IDBITNOVO_BASE_URL- Bitnovo API URL
Transport Mode Detection:
If
PORTenv var is set โ HTTP mode (remote connections)If no
PORTโ stdio mode (local connections)
๐ฆ Installation Options
Option A: Using npx (Recommended)
No installation required! The npx command automatically downloads and runs the latest version.
npx -y @bitnovopay/mcp-bitnovo-payAdvantages:
โ Always get the latest version
โ No manual updates needed
โ No local installation required
โ Works immediately
Option B: Clone Repository (For Development)
For contributors or advanced users who need to modify the code:
# 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 startAdvantages:
โ Full control of source code
โ Ability to modify and test changes
โ Ideal for contributing to the project
๐ง Configuration by LLM Platform
Choose your AI platform and follow the specific setup guide:
Claude Desktop (Anthropic)
Config File Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Guide: Claude Setup Guide
Basic Configuration:
{
"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"
}
}
}
}With Webhooks (for real-time payment notifications):
{
"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
Guide: OpenAI Setup Guide Supported: GPT-5, GPT-4o, Responses API, Agents SDK
Basic Configuration:
{
"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
Guide: Gemini Setup Guide Supported: Gemini 2.5 Flash/Pro (Sept 2025), CLI, FastMCP
Basic Configuration:
{
"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"
}
}
}
}Environment Variables
Variable | Required | Description | Example |
| โ Yes | Your Bitnovo Pay device identifier |
|
| โ Yes | Bitnovo API endpoint |
|
| โ ๏ธ Optional | HMAC secret for webhook validation |
|
| โ ๏ธ Optional | Enable webhook server |
|
| โ ๏ธ Optional | Auto-start tunnel for webhooks |
|
| โ ๏ธ Optional | Tunnel provider |
|
Security Note: Never commit credentials to version control. Use environment variables or secure secret management.
๐ ๏ธ MCP Tools Reference
Payment Creation
create_payment_onchain
Creates a cryptocurrency payment with a specific address for direct transactions.
Use when: User specifies a cryptocurrency (Bitcoin, ETH, USDC, etc.)
{
"amount_eur": 50.0,
"input_currency": "BTC",
"notes": "Coffee payment"
}create_payment_link
Creates a web-based payment URL where customers can choose their cryptocurrency.
Use when: Generic payment request without specific crypto mentioned (DEFAULT OPTION)
{
"amount_eur": 50.0,
"url_ok": "https://mystore.com/success",
"url_ko": "https://mystore.com/cancel",
"notes": "Order #1234"
}Payment Management
get_payment_status
Retrieves current payment status with detailed information.
{
"identifier": "payment_id_here"
}Status Codes:
NR(Not Ready): Pre-payment created, no crypto assignedPE(Pending): Waiting for customer paymentAC(Awaiting Completion): Crypto detected in mempoolCO(Completed): Payment confirmed on blockchainEX(Expired): Payment time limit exceededCA(Cancelled): Payment cancelledFA(Failed): Transaction failed to confirm
list_currencies_catalog
Gets available cryptocurrencies with optional amount-based filtering.
{
"filter_by_amount": 25.0
}generate_payment_qr
Creates custom QR codes for existing payments with high-quality output.
{
"identifier": "payment_id_here",
"qr_type": "both",
"size": 512,
"style": "branded"
}QR Types:
address: Crypto address only (customer enters amount manually)payment_uri: Address + amount included (recommended)both: Generate both types (recommended)gateway_url: QR of payment gateway URL
QR Size Options (v1.1.0+):
Default: 512px (optimized for modern displays)
Range: 100px - 2000px
Recommended sizes:
512px: Mobile and web displays800-1200px: Standard printing1600-2000px: High-quality printing (posters, stands)
Quality Improvements (v1.1.0):
โจ Sharp edges with
nearestkernel interpolation for QR patterns๐ฏ High-quality logo scaling with
lanczos3kernel๐ฆ PNG compression level 6 with adaptive filtering
๐ผ๏ธ Default size increased from 300px to 512px for better clarity
Webhook Tools
get_webhook_events
Query webhook events received in real-time from Bitnovo Pay API.
Available when: WEBHOOK_ENABLED=true
{
"identifier": "payment_id_here",
"limit": 50,
"validated_only": true
}get_webhook_url
Get public webhook URL with configuration instructions for Bitnovo panel.
Available when: WEBHOOK_ENABLED=true
{
"validate": true
}get_tunnel_status
Diagnose tunnel connection status (ngrok, zrok, or manual).
Available when: WEBHOOK_ENABLED=true
{}๐ Documentation
API Tools Reference - Detailed documentation for all MCP tools
Usage Examples - Real-world usage examples
Error Handling - Error codes and troubleshooting
Webhook System - Webhook configuration and tunnel management
๐๏ธ Development
Available Scripts
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 PrettierArchitecture
โโโโโโโโโโโโโโโโโโโ
โ 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/) โ
โโโโโโโโโโโโโโโโโโโDual-Server Architecture
The MCP server can run two servers simultaneously:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 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)๐ Security
HTTPS Only - All API calls use HTTPS
HMAC Validation - Webhook signature verification with SHA-256
Replay Attack Prevention - Nonce caching with 5-minute TTL
Data Privacy - Sensitive information is masked in logs
No Rate Data - Exchange rates not exposed to prevent inaccuracies
Stateless Design - No local persistence, real-time API queries
Auto-reconnection - Exponential backoff up to 10 retries for tunnels
Health Monitoring - Connection verification every 60 seconds
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ค Contributing
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
๐ Support
Issues: GitHub Issues
Bitnovo Support: https://www.bitnovo.com/
MCP Protocol: https://modelcontextprotocol.io/
๐ Related
Model Context Protocol - Official MCP specification
Bitnovo Pay - Cryptocurrency payment platform
Bitnovo Pay - Documentation - Bitnovo Pay Official Documentation
Bitnovo Pay - Documenciรณn en Espaรฑol - Bitnovo Pay Documentaciรณn Oficial
MCP SDK - Official MCP SDK for TypeScript
Available Tools
5 toolscreate_payment_linkA
Create payment link/URL where customer chooses cryptocurrency. USE AS DEFAULT WHEN: User requests payment without specifying crypto. Customer clicks link and selects their preferred cryptocurrency from available options. RESULT: Returns a web_url that you share with your customer. EXAMPLES: "Payment for 50 euros", "Create payment", "Generate QR", "Payment link", "dame el qr para un pago de 24 euros". PREFERRED for all generic payment requests. NOTE: Customer can choose ANY available cryptocurrency in the gateway. IMPORTANT: Only provide url_ok and url_ko if user explicitly requests redirect URLs - DO NOT invent or assume redirect URLs.
Inputs: amount_eur (required), url_ok, url_ko, fiat, +2 more.
create_payment_onchainA
๐จ CRITICAL RULE #1 - EXPIRATION: YOU MUST tell user payment expires in EXACTLY "expires_in_minutes" MINUTES. Convert "expires_at" (UTC) to user's LOCAL TIME ZONE and display in their language. Format: "expires in X minutes (on [date] at [time] [user's timezone])".
๐ฐ CRITICAL RULE #2 - AMOUNT: YOU MUST show "expected_input_amount" with FULL PRECISION (all decimals). Example: "0.43515861 SOL" not "0.44 SOL". This is the EXACT amount customer must send.
๐ช RULE #3 - DISPLAY: Show users ONLY "original_symbol" (BTC, USDC, SOL) and "original_blockchain" (Bitcoin Network, Solana Test Network). NEVER mention internal codes.
๐ CRITICAL RULE #4 - PAYMENT LINK: ALWAYS display "web_url" as "Enlace de pago:" or "Payment Link:" in user's language. This is the web gateway URL where customers can view and complete the payment.
๐ฏ WHEN TO USE: Only when user explicitly mentions a cryptocurrency (Bitcoin, BTC, Ethereum, ETH, USDC, Solana, SOL, etc.). Customer MUST pay with that exact crypto.
๐ NETWORK SELECTION: If crypto has MULTIPLE networks (check network_groups), call list_currencies_catalog first, ASK USER which network. Pass cryptocurrency as "SYMBOL on NETWORK".
EXAMPLES: cryptocurrency="BTC", cryptocurrency="USDC on Ethereum Network", cryptocurrency="SOL on Solana Test Network".
Inputs: amount (required), cryptocurrency (required), fiat, notes, +1 more.
generate_payment_qrA
Generate QR codes for payment address and/or payment URI from an existing payment. USE THIS WHEN: User wants QR in different size/style than original, User wants only address QR or only payment URI QR (not both), User created payment without QR (include_qr=false) and now needs it, User wants QR for gateway URL (for redirect payments). EXAMPLES: "Generate bigger QR", "Create QR without branding", "I need QR of 500px", "Generate QR for the payment link"
Inputs: identifier (required), qr_type, size, style, +2 more.
get_payment_statusA
Query the current status and details of a payment by its unique identifier. USE THIS WHEN: User wants to check if a payment was completed, or get details about a previously created payment. RESULT: Payment status (PE=Pending, CO=Completed, EX=Expired, CA=Cancelled), amounts, and confirmation info. Status descriptions: PE (Pending): Waiting for customer to pay, CO (Completed): Payment confirmed on blockchain, EX (Expired): Payment time limit exceeded, CA (Cancelled): Payment was cancelled. EXAMPLES: "Check payment status", "Is payment abc-123 completed?", "Status of my payment". Note: Exchange rate is not included in response as it may not be accurate for non-EUR fiat currencies.
Inputs: identifier (required).
list_currencies_catalogA
Get available cryptocurrencies with optional amount filtering. USE WHEN: (1) User asks which cryptos available, (2) BEFORE onchain payment if crypto has multiple networks (e.g., USDC). DISPLAY RULES: Show users "original_symbol" (BTC, USDC) and "original_blockchain" (Bitcoin Network, Ethereum Network). Use "input_currency_code" ONLY when calling create_payment_onchain - NEVER show it to users. NETWORK SELECTION: If multiple networks exist (shown in network_groups), ASK user which network. RESULT: List with min/max amounts, decimals, network info, features. EXAMPLES: "Which cryptos available?", "What currencies support 50 euros?"
Inputs: filter_by_amount.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 5 tools
Each tool targets a distinct action: creating payment links, creating onchain payments with specific crypto, generating QRs for existing payments, checking status, and listing currencies. No overlap.
All tool names follow the verb_noun pattern in snake_case (create_payment_link, create_payment_onchain, generate_payment_qr, get_payment_status, list_currencies_catalog), making them predictable.
Five tools cover essential payment operations: creation (generic and specific), QR generation, status checking, and currency catalog. This is well-scoped for the server's purpose.
The set covers creation, QR, status, and catalog. A minor gap is the lack of a dedicated cancel/refund tool, though status includes a cancelled state. Otherwise complete.
Maintenance
Related MCP Connectors
Let AI agents add Yolfi crypto checkout, paylinks, webhooks, and status checks.
Crypto pay links and API for people and AI agents. BTC, Lightning, USDC, USDT, EURC, SOL, ETH.
Crypto payments for AI agents: self-serve account, invoices, receiving, payouts, exchange.
Non-custodial crypto payments for AI assistants: balances, payments, and create payment links.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceConnects the Payoza crypto payments API to AI assistants, enabling users to manage transactions, subscriptions, and payment links across multiple blockchains. It provides a comprehensive suite of tools for handling checkout sessions, customers, and real-time revenue analytics through natural language commands.-
- AlicenseAqualityAmaintenanceEnables AI assistants to interact with the Bit2Me cryptocurrency ecosystem, including real-time market data, wallet management, trading, and products like Earn and Loans.48694 npm5MIT
- FlicenseNot gradedqualityAmaintenanceLets AI coding agents integrate crypto checkout, payment links, payment status checks, and webhook-based entitlements into applications.-
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to add stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based access logic to applications. It provides tools for registering workspaces, configuring settlement wallets and webhooks, creating paylinks, and verifying crypto payment status.MIT