Overview

This MCP (Model Context Protocol) server integrates Bitnovo Pay into AI agents, exposing payment-related operations as MCP tools. It lets agents create crypto payments, check statuses, produce branded QR codes, and receive webhook events through an automatically managed tunnel (ngrok, zrok) or a manual public endpoint. The server supports both local stdio transport (for desktop MCP clients) and HTTP transport (for cloud deployments), enabling flexible workflows for development, testing, and production.

Designed for developers who want to add crypto payment capabilities to conversational agents or automation systems, the server handles Bitnovo Pay API interactions, webhook delivery, signature verification, retry/backoff, and privacy-conscious logging so agents can operate without embedding secret logic.

GitHub: https://github.com/bitnovo/mcp-bitnovo-pay

Features

Eight MCP tools covering payment creation, status lookup, currency catalog, QR generation, and webhook management
Webhook tunneling with three modes:
- ngrok (persistent public URL per account)
- zrok (open-source, persistent URLs)
- manual (use your server/VPS public IP or reverse proxy)
Supports stdio and HTTP transport modes (auto-detected by PORT env var)
High-resolution QR code generation (512px default, up to 2000px)
HMAC webhook signature validation and HTTPS enforcement
Masked logging for sensitive fields and robust retry/timeouts
Stateless operation so it can run in serverless or containerized environments

Installation / Configuration

Prerequisites:

Node.js >= 18
Bitnovo Pay account (Device ID, optional Device Secret)

Quick start with npx (recommended):

npx -y @bitnovopay/mcp-bitnovo-pay

Run with environment variables (example for local/stdio usage):

BITNOVO_DEVICE_ID=your_device_id \
BITNOVO_BASE_URL=https://pos.bitnovo.com \
npx -y @bitnovopay/mcp-bitnovo-pay

Docker (recommended for cloud/container deployment):

docker build -t mcp-bitnovo-pay .
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

Example MCP client configuration (Claude Desktop / ChatGPT):

{
  "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 (key ones):

Variable	Description
PORT	If set, server runs in HTTP mode and listens on this port
BITNOVO_DEVICE_ID	Required device identifier from Bitnovo Pay
BITNOVO_DEVICE_SECRET	Optional, used to validate incoming webhook signatures
BITNOVO_BASE_URL	Base URL for Bitnovo API (default: https://pos.bitnovo.com)

Transport mode selection:

If PORT is defined → HTTP transport (remote clients can call /mcp)
If PORT is unset → stdio transport (local MCP clients via npx)

Available Tools

Each tool is exposed as an MCP function an agent can invoke:

create_payment_onchain: generate an on-chain address for direct crypto payment
create_payment_link: produce a web payment URL and optional redirect handling
get_payment_status: retrieve current payment status and metadata
list_currencies_catalog: list supported currencies with filters
generate_payment_qr: render a high-resolution QR from a payment object
get_webhook_events: fetch webhook events the server has received
get_webhook_url: return the public webhook URL and tunnel configuration tips
get_tunnel_status: show active tunnel provider and connection health

Use Cases

In-chat payment flows: An assistant creates a 10 EUR payable link or on-chain address and returns a QR code the user can scan.
- Example: Ask your MCP-enabled assistant: “Create a payment for 10 euros” → agent calls create_payment_link and generate_payment_qr.
Point-of-sale integrations: Create on-chain addresses for in-person payments and monitor status with get_payment_status until confirmed.
Webhook-driven workflows: Use ngrok or zrok during development to surface Bitnovo Pay webhook events to a local agent for immediate processing (order fulfillment, notifications).
Cloud deployment: Run the server on Railway, Cloud Run, Fly.io, or AWS with HTTP transport to integrate with hosted LLM platforms that require a public MCP endpoint.

Concrete example (create link + QR via agent):

Agent calls create_payment_link with amount and currency.
Agent calls generate_payment_qr with the returned payment ID and desired resolution.
Agent sends the QR image to user and polls get_payment_status until settlement.

Deployment Notes & Best Practices

For development use zrok or ngrok for instant public URLs; prefer zrok for a fully open-source option.
Keep BITNOVO_DEVICE_SECRET secret and configure HMAC validation to verify webhook authenticity.
Use HTTPS and run behind a reverse proxy when exposing the HTTP transport in production.
Enable logging masking and review webhook events in get_webhook_events for troubleshooting.

For more details, examples, and advanced configuration see the repository: https://github.com/bitnovo/mcp-bitnovo-pay

Bitnovo Pay MCP Server for Crypto Payments