Bitnovo Pay

Official

by bitnovo

312 downloads Not rated yet

GitHub Website

About

MCP server for Bitnovo Pay integration with AI agents. Provides cryptocurrency payment capabilities through Bitnovo Pay API. Features include payment creation, status checking, QR code generation, and webhook management with support for multiple tunnel providers (ngrok, zrok, man

Explore

- 8 MCP tools for complete payment management:
- create_payment_onchain - Generate cryptocurrency addresses for direct payments
- create_payment_link - Create web payment URLs with redirect management
- 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 the 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)

- Compatible with multiple LLMs:
- 🤖 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+):
- 📱 Default resolution of 512px (improved 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

- Security and privacy:
- Mandatory HTTPS communication
- HMAC signature validation for webhooks
- Replay attack prevention with nonce cache
- Sensitive data masked in logs
- No local storage (stateless operation)

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Bitnovo Pay

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

From the repository

{% hint style="info" %}
Before starting, make sure you have:
{% endhint %}

| Requirement | Description | Needed for |
|-------------|-------------|------------|
| ✅ Node.js 18+ | JavaScript runtime | Running MCP server |
| ✅ Bitnovo Pay Account | Registration at bitnovo.com/pay | Obtain credentials |
| ✅ Device ID | Device identifier from dashboard | All operations |
| ⚠️ Device Secret | HMAC secret (optional) | Webhooks with validation |
| ✅ MCP Client | Claude, ChatGPT, or Gemini | Interact with server |
| ⚠️ ngrok/zrok (optional) | Tunnel for webhooks | Local development with webhooks |

{% hint style="success" %}
Quick start: You only need Node.js 18+ and Bitnovo credentials to begin. Webhooks are optional.
{% endhint %}

Add this configuration to your MCP client (example for Claude Desktop):

``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" } } } }`{% hint style="warning" %} Configuration file location: - Claude Desktop (macOS):~/Library/Application Support/Claude/claude_desktop_config.json- Claude Desktop (Windows):%APPDATA%\Claude\claude_desktop_config.json- OpenAI ChatGPT:~/.config/openai/mcp-config.json- Google Gemini:~/.config/gemini/mcp-config.json{% endhint %}


npm install
Get your credentials from the Bitnovo Pay dashboard:

- Device ID: Unique identifier for your merchant

- Device Secret: (Required for webhooks) For HMAC signature validation

- Base URL: Environment URL (development or production)

`json { "mcpServers": { "bitnovo-pay": { "command": "npx", "args": ["@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" } } } }

json

{

  "mcpServers": {

    "bitnovo-pay": {

      "command": "npx",

      "args": ["@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": "bitnovo-dev.ngrok-free.app"

      }

    }

  }

}



json

{

  "mcpServers": {

    "bitnovo-pay": {

      "command": "npx",

      "args": ["@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": "false",

        "WEBHOOK_PUBLIC_URL": "https://n8n.company.com"

      }

    }

  }

}





Supported since: 2025

User request: > "How do I configure webhooks in Bitnovo?" Tool:get_webhook_urlCommand:`json { "validate": true }`Result: Webhook URL + step-by-step instructions to configure in Bitnovo dashboard.


TUNNEL_ENABLED=true

TUNNEL_PROVIDER=ngrok  # Options: ngrok, zrok, manual

{% hint style="warning" %} Security best practices: - ✅ Use environment variables, never hardcode secrets - ✅ RotateBITNOVO_DEVICE_SECRETregularly - ✅ Use production URLs (https://pos.bitnovo.com) in production environments - ✅ Limit access to MCP configuration file (permissions 600) - ❌ NEVER shareBITNOVO_DEVICE_SECRET` in logs, repos, or messages
{% endhint %}

Recommended permissions for configuration file:

chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

chmod 600 ~/.config/openai/mcp-config.json

Event Store:
- Estimated memory per event: ~2KB
- 1000 events ≈ 2MB
- 10000 events ≈ 20MB

Tunnel Manager:
- ngrok: ~5-10MB overhead
- zrok: ~10-20MB overhead (includes OpenZiti)
- manual: ~0MB (no tunnel process)

Cause: Amount outside cryptocurrency limits.

Solutions:
1. Check limits with list_currencies_catalog
2. Adjust amount within allowed range
3. For large payments, consider splitting into multiple transactions

Example of limits query:
``json // Request { "filter_by_amount": 50.0 } // Response shows min_amount and max_amount [ { "symbol": "BTC", "min_amount": 0.01, "max_amount": null // No upper limit } ]``

---

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "bitnovo pay": {
            "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"
                }
            }
        }
    }
}

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

1. Introduction 2. What is MCP? 3. Quick Start (5 minutes) 4. Main Features 5. Prerequisites 6. Installation 7. Platform Configuration 8. MCP Tools Reference 9. Webhooks and Tunnels System 10. Security 11. Usage Examples 12. Troubleshooting ---

Introduction

The Bitnovo Pay MCP server allows AI agents to interact with the Bitnovo Pay API to create and manage cryptocurrency payments autonomously. This integration facilitates crypto payment automation in applications using language models like ChatGPT, Claude, or Gemini. {% hint style="success" %} Current version: v1.1.0 | Last update: September 30, 2025 {% endhint %} ---

What is MCP?

Model Context Protocol (MCP) is an open standard protocol that allows AI models to access external tools and services in a structured and secure manner.

Key MCP Concepts

| Concept | Description | |---------|-------------| | MCP Server | Process that exposes capabilities (tools, resources) through the MCP protocol via stdio | | MCP Tools | Functions that the AI model can invoke (e.g., create_payment_link) | | MCP Resources | Data that the server can provide to the model (e.g., cryptocurrency catalog) | | stdio Transport | Communication between MCP client and server using standard input/output | The Bitnovo Pay MCP server implements this protocol to expose 8 MCP tools that enable complete crypto payment management from any compatible MCP client. {% hint style="info" %} Official specification: modelcontextprotocol.io {% endhint %} ---

Quick Start (5 minutes)

Step 1: Get your credentials

1. Create an account at Bitnovo Pay 2. Obtain your Device ID from the Bitnovo dashboard 3. (Optional) Generate Device Secret for webhooks

Step 2: Configure your MCP client

Add this configuration to your MCP client (example for Claude Desktop): ``

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



{% hint style="warning" %}
Configuration file location:
- Claude Desktop (macOS):

~/Library/Application Support/Claude/claude_desktop_config.json


- Claude Desktop (Windows):

%APPDATA%\Claude\claude_desktop_config.json


- OpenAI ChatGPT:

~/.config/openai/mcp-config.json


- Google Gemini:

~/.config/gemini/mcp-config.json


{% endhint %}

Step 3: Restart your MCP client


Restart Claude Desktop, ChatGPT, or your MCP client to load the server.

Step 4: Test it!


Ask your AI assistant:

> _"Create a payment for 10 euros"_

✅ You should receive a payment URL ready to share.

---

Main Features


- 8 MCP tools for complete payment management:
  -

create_payment_onchain

 - Generate cryptocurrency addresses for direct payments
  -

create_payment_link

 - Create web payment URLs with redirect management
  -

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 the 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)

- Compatible with multiple LLMs:
  - 🤖 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+):
  - 📱 Default resolution of 512px (improved 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

- Security and privacy:
  - Mandatory HTTPS communication
  - HMAC signature validation for webhooks
  - Replay attack prevention with nonce cache
  - Sensitive data masked in logs
  - No local storage (stateless operation)

Prerequisites


{% hint style="info" %}
Before starting, make sure you have:
{% endhint %}

| Requirement | Description | Needed for |
|-------------|-------------|------------|
| ✅ Node.js 18+ | JavaScript runtime | Running MCP server |
| ✅ Bitnovo Pay Account | Registration at bitnovo.com/pay | Obtain credentials |
| ✅ Device ID | Device identifier from dashboard | All operations |
| ⚠️ Device Secret | HMAC secret (optional) | Webhooks with validation |
| ✅ MCP Client | Claude, ChatGPT, or Gemini | Interact with server |
| ⚠️ ngrok/zrok (optional) | Tunnel for webhooks | Local development with webhooks |

{% hint style="success" %}
Quick start: You only need Node.js 18+ and Bitnovo credentials to begin. Webhooks are optional.
{% endhint %}

Installation


There are two ways to install the Bitnovo Pay MCP server:

Option 1: Using npx (Recommended)


{% hint style="success" %}
Recommended for most users - Simplest way and always up-to-date
{% endhint %}

No prior installation required, just configure your MCP client (see "Platform Configuration" section below) using:

bash
npx -y @bitnovopay/mcp-bitnovo-pay



✅ Advantages:
- Always get the latest published version
- No need to clone the repository
- No need to compile the code
- Automatic updates on each execution
- Perfect for end users

Option 2: Clone the repository (For development)


{% hint style="warning" %}
For developers only - Requires TypeScript and Node.js knowledge
{% endhint %}

If you need to modify the code or contribute to the project:

``bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Explore

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Table of Contents

Introduction

What is MCP?

Key MCP Concepts

Quick Start (5 minutes)

Step 1: Get your credentials

Step 2: Configure your MCP client

Step 3: Restart your MCP client

Step 4: Test it!

Main Features

Prerequisites

Installation

Option 1: Using npx (Recommended)

Option 2: Clone the repository (For development)

More like this

Sequential Thinking

Sentry

Github

Filesystem