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 payments
  • create_payment_link - Create web payment URLs with redirect handling
  • get_payment_status - Query payment status with detailed information
  • list_currencies_catalog - Get supported cryptocurrencies with filtering
  • generate_payment_qr - Generate custom QR codes from existing payments
  • get_webhook_events - Query webhook events received in real-time
  • get_webhook_url - Get public webhook URL with configuration instructions
  • get_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

📋 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

1. Sign up at Bitnovo Pay
2. Obtain your Device ID from the Bitnovo dashboard
3. (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:

1. Click "Deploy to Railway" or create a new project
2. Set environment variables:
   • BITNOVO_DEVICE_ID - Your Bitnovo device ID
   • BITNOVO_BASE_URL - https://pos.bitnovo.com
3. Deploy (Railway auto-detects Dockerfile)
4. 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-pay

Deploy 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.toml configuration
• Google 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 ID
• BITNOVO_BASE_URL - Bitnovo API URL

Transport Mode Detection:

• If PORT env 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-pay

Advantages:

• ✅ 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 start

Advantages:

• ✅ 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
BITNOVO_DEVICE_ID	✅ Yes	Your Bitnovo Pay device identifier	12345678-abcd-1234-abcd-1234567890ab
BITNOVO_BASE_URL	✅ Yes	Bitnovo API endpoint	https://pos.bitnovo.com (production)<br>https://payments.pre-bnvo.com (development)
BITNOVO_DEVICE_SECRET	⚠️ Optional	HMAC secret for webhook validation	your_hex_secret
WEBHOOK_ENABLED	⚠️ Optional	Enable webhook server	true or false
TUNNEL_ENABLED	⚠️ Optional	Auto-start tunnel for webhooks	true or false
TUNNEL_PROVIDER	⚠️ Optional	Tunnel provider	ngrok, zrok, or manual

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 assigned
• PE (Pending): Waiting for customer payment
• AC (Awaiting Completion): Crypto detected in mempool
• CO (Completed): Payment confirmed on blockchain
• EX (Expired): Payment time limit exceeded
• CA (Cancelled): Payment cancelled
• FA (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 displays
  • 800-1200px: Standard printing
  • 1600-2000px: High-quality printing (posters, stands)

Quality Improvements (v1.1.0):

• ✨ Sharp edges with nearest kernel interpolation for QR patterns
• 🎯 High-quality logo scaling with lanczos3 kernel
• 📦 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 Prettier

Architecture

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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