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

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

Payme

---