Bitnovo Pay

offiziell

MCP-Server für die Integration von Bitnovo Pay mit KI-Agenten. Bietet Kryptowährungszahlungsfunktionen über die Bitnovo Pay API. Zu den Funktionen gehören Zahlungserstellung, Statusprüfung, QR-Code-Generierung und Webhook-Verwaltung mit Unterstützung für mehrere Tunnelanbieter (ngrok, zrok, manuell).

GitHub

Was kann man mit Bitnovo Pay MCP machen?

Create an on-chain crypto payment — Bitten Sie Ihren Assistenten, mit create_payment_onchain eine Kryptowährungsadresse für eine bestimmte Coin und einen Euro-Betrag zu generieren.
Create a shareable payment link — Lassen Sie Ihren Assistenten eine Web-Zahlungs-URL erstellen, bei der Kunden ihre Kryptowährung über create_payment_link wählen.
Check payment status — Fordern Sie den aktuellen Status und die Details einer beliebigen Zahlung anhand ihrer Kennung mit get_payment_status an.
List supported currencies — Rufen Sie verfügbare Kryptowährungen ab, optional gefiltert nach einem Mindest-Euro-Betrag, mit list_currencies_catalog.
Generate a branded payment QR — Erstellen Sie einen hochauflösenden QR-Code für eine bestehende Zahlung mit generate_payment_qr.
Inspect webhook events — Fragen Sie Echtzeit-Zahlungsbenachrichtigungen ab, die von Bitnovo über get_webhook_events empfangen wurden.

Dokumentation

MCP Bitnovo Pay

MCP-Server für die Bitnovo Pay-Integration mit KI-Agenten

Ein Model Context Protocol (MCP)-Server, der KI-Agenten Kryptowährungs-Zahlungsfunktionen über die Bitnovo Pay API-Integration bereitstellt. Dieser Server ermöglicht KI-Modellen das Erstellen von Zahlungen, die Überprüfung des Zahlungsstatus, die Verwaltung von QR-Codes und den Zugriff auf Kryptowährungs-Kataloge.

🚀 Funktionen

8 MCP-Tools für umfassendes Zahlungsmanagement:
- create_payment_onchain - Kryptowährungs-Adressen für Direktzahlungen generieren
- create_payment_link - Web-Zahlungs-URLs mit Weiterleitungsbehandlung erstellen
- get_payment_status - Zahlungsstatus mit detaillierten Informationen abfragen
- list_currencies_catalog - Unterstützte Kryptowährungen mit Filterung abrufen
- generate_payment_qr - Benutzerdefinierte QR-Codes aus bestehenden Zahlungen generieren
- get_webhook_events - In Echtzeit empfangene Webhook-Ereignisse abfragen
- get_webhook_url - Öffentliche Webhook-URL mit Konfigurationsanweisungen abrufen
- get_tunnel_status - Tunnel-Verbindungsstatus diagnostizieren
Automatisches Webhook-System mit 3 Tunnel-Anbietern:
- 🔗 ngrok: Kostenlose permanente URL (1 statische Domain pro Konto)
- 🌐 zrok: 100 % kostenlos, Open-Source mit permanenten URLs
- 🏢 manuell: Für Server mit öffentlicher IP (N8N, Opal, VPS)
Multi-LLM-Unterstützung - Kompatibel mit:
- 🤖 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)
Hochwertige QR-Codes (v1.1.0+):
- 📱 512px Standardauflösung (vorher 300px) für moderne Displays
- 🖨️ Unterstützung bis zu 2000px für professionellen Druck
- ✨ Scharfe Kanten durch optimierte Interpolationsalgorithmen
- 🎨 Benutzerdefiniertes Bitnovo Pay-Branding mit sanfter Logo-Skalierung
Datenschutz als Standard - Sensible Daten in Protokollen maskiert, minimale Datenweitergabe
Sicher - HTTPS-Erzwingung, HMAC-Signaturvalidierung, sichere Geheimnisverwaltung
Zuverlässig - Integrierte Wiederholungslogik, Timeout-Behandlung, zustandsloser Betrieb

📋 Voraussetzungen

Node.js 18+
Bitnovo Pay-Konto mit Geräte-ID und optionalem Geräte-Geheimnis
Umgebungskonfiguration (siehe Einrichtungsanleitungen unten)

⚡ Schnellstart

1. Holen Sie sich Ihre Bitnovo-Anmeldedaten

Registrieren Sie sich bei Bitnovo Pay
Erhalten Sie Ihre Geräte-ID aus dem Bitnovo-Dashboard
(Optional) Generieren Sie ein Geräte-Geheimnis für die Webhook-Signaturvalidierung

2. Konfigurieren Sie Ihren MCP-Client

Fügen Sie diese Konfiguration zur Konfigurationsdatei Ihres MCP-Clients hinzu:

Für 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"
      }
    }
  }
}

Für OpenAI ChatGPT (siehe OpenAI-Einrichtungsanleitung):

{
  "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. Starten Sie Ihren MCP-Client neu

Starten Sie Claude Desktop, ChatGPT oder Ihren MCP-Client neu, um den Server zu laden.

4. Testen Sie die Integration

Fragen Sie Ihren KI-Assistenten: "Erstelle eine Zahlung über 10 Euro"

☁️ Cloud-Bereitstellung (NEU in v1.2.0)

MCP Bitnovo Pay unterstützt jetzt die Remote-Bereitstellung auf Cloud-Plattformen mit HTTP-Transportmodus. Dies ermöglicht KI-Plattformen wie claude.ai, sich remote mit Ihrem MCP-Server zu verbinden.

Bereitstellung auf Railway (Empfohlen)

Schnelleinrichtung:

Klicken Sie auf „Auf Railway bereitstellen“ oder erstellen Sie ein neues Projekt
Setzen Sie Umgebungsvariablen:
- BITNOVO_DEVICE_ID - Ihre Bitnovo-Geräte-ID
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Bereitstellen (Railway erkennt Dockerfile automatisch)
Holen Sie sich Ihre öffentliche URL: https://your-app.up.railway.app

Mit claude.ai verbinden:

Server hinzufügen unter Einstellungen → Model Context Protocol
Server-URL: https://your-app.up.railway.app/mcp

📖 Vollständige Anleitung: Siehe RAILWAY.md für detaillierte Bereitstellungsanweisungen, Fehlerbehebung und Konfiguration.

Bereitstellung mit 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

Bereitstellung auf anderen Plattformen

Der Server funktioniert auf jeder Plattform, die Node.js und Docker unterstützt:

Heroku: Dockerfile mit Umgebungsvariablen pushen
Fly.io: Bereitstellung mit fly.toml-Konfiguration
Google Cloud Run: Docker-Container bereitstellen
AWS ECS/Fargate: Bereitstellung mit Task-Definition

Erforderliche Umgebungsvariablen:

PORT - HTTP-Port (wird von den meisten Plattformen automatisch gesetzt)
BITNOVO_DEVICE_ID - Ihre Bitnovo-Geräte-ID
BITNOVO_BASE_URL - Bitnovo API-URL

Transportmodus-Erkennung:

Wenn PORT Umgebungsvariable gesetzt ist → HTTP-Modus (Remote-Verbindungen)
Wenn kein PORT → stdio-Modus (lokale Verbindungen)

📦 Installationsoptionen

Option A: Verwendung von npx (Empfohlen)

Keine Installation erforderlich! Der Befehl npx lädt automatisch die neueste Version herunter und führt sie aus.

npx -y @bitnovopay/mcp-bitnovo-pay

Vorteile:

✅ Immer die neueste Version erhalten
✅ Keine manuellen Updates erforderlich
✅ Keine lokale Installation erforderlich
✅ Funktioniert sofort

Option B: Repository klonen (Für Entwicklung)

Für Mitwirkende oder fortgeschrittene Benutzer, die den Code ändern müssen:

# 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

Vorteile:

✅ Volle Kontrolle über den Quellcode
✅ Möglichkeit, Änderungen zu modifizieren und zu testen
✅ Ideal, um zum Projekt beizutragen

🔧 Konfiguration nach LLM-Plattform

Wählen Sie Ihre KI-Plattform und folgen Sie der spezifischen Einrichtungsanleitung:

Claude Desktop (Anthropic)

Konfigurationsdatei-Speicherort: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Anleitung: Claude-Einrichtungsanleitung

Grundkonfiguration:

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

Mit Webhooks (für Echtzeit-Zahlungsbenachrichtigungen):

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

Anleitung: OpenAI-Einrichtungsanleitung Unterstützt: GPT-5, GPT-4o, Responses API, Agents SDK

Grundkonfiguration:

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

Anleitung: Gemini-Einrichtungsanleitung Unterstützt: Gemini 2.5 Flash/Pro (Sept 2025), CLI, FastMCP

Grundkonfiguration:

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

Umgebungsvariablen

Variable	Erforderlich	Beschreibung	Beispiel
`BITNOVO_DEVICE_ID`	✅ Ja	Ihre Bitnovo Pay-Gerätekennung	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ Ja	Bitnovo API-Endpunkt	`https://pos.bitnovo.com` (Produktion) `https://payments.pre-bnvo.com` (Entwicklung)
`BITNOVO_DEVICE_SECRET`	⚠️ Optional	HMAC-Geheimnis für Webhook-Validierung	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ Optional	Webhook-Server aktivieren	`true` oder `false`
`TUNNEL_ENABLED`	⚠️ Optional	Tunnel für Webhooks automatisch starten	`true` oder `false`
`TUNNEL_PROVIDER`	⚠️ Optional	Tunnel-Anbieter	`ngrok`, `zrok` oder `manual`

Sicherheitshinweis: Geben Sie niemals Anmeldedaten in die Versionskontrolle. Verwenden Sie Umgebungsvariablen oder sichere Geheimnisverwaltung.

🛠️ MCP-Tools-Referenz

Zahlungserstellung

`create_payment_onchain`

Erstellt eine Kryptowährungszahlung mit einer spezifischen Adresse für direkte Transaktionen.

Verwendung wenn: Benutzer eine Kryptowährung angibt (Bitcoin, ETH, USDC, etc.)

{
  "amount_eur": 50.0,
  "input_currency": "BTC",
  "notes": "Coffee payment"
}

`create_payment_link`

Erstellt eine webbasierte Zahlungs-URL, bei der Kunden ihre Kryptowährung auswählen können.

Verwendung wenn: Allgemeine Zahlungsanforderung ohne Angabe einer bestimmten Kryptowährung (STANDARDOPTION)

{
  "amount_eur": 50.0,
  "url_ok": "https://mystore.com/success",
  "url_ko": "https://mystore.com/cancel",
  "notes": "Order #1234"
}

Zahlungsverwaltung

`get_payment_status`

Ruft den aktuellen Zahlungsstatus mit detaillierten Informationen ab.

{
  "identifier": "payment_id_here"
}

Statuscodes:

NR (Nicht bereit): Vorauszahlung erstellt, keine Krypto zugewiesen
PE (Ausstehend): Warten auf Kundenzahlung
AC (Abschluss erwartet): Krypto im Mempool erkannt
CO (Abgeschlossen): Zahlung auf der Blockchain bestätigt
EX (Abgelaufen): Zahlungsfrist überschritten
CA (Storniert): Zahlung storniert
FA (Fehlgeschlagen): Transaktion konnte nicht bestätigt werden

`list_currencies_catalog`

Ruft verfügbare Kryptowährungen mit optionaler betragsbasierter Filterung ab.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

Erstellt benutzerdefinierte QR-Codes für bestehende Zahlungen mit hochwertiger Ausgabe.

{
  "identifier": "payment_id_here",
  "qr_type": "both",
  "size": 512,
  "style": "branded"
}

QR-Typen:

address: Nur Krypto-Adresse (Kunde gibt Betrag manuell ein)
payment_uri: Adresse + Betrag enthalten (empfohlen)
both: Beide Typen generieren (empfohlen)
gateway_url: QR-Code der Zahlungs-Gateway-URL

QR-Größenoptionen (v1.1.0+):

Standard: 512px (optimiert für moderne Displays)
Bereich: 100px - 2000px
Empfohlene Größen:
- 512px: Mobile und Web-Displays
- 800-1200px: Standarddruck
- 1600-2000px: Hochwertiger Druck (Poster, Ständer)

Qualitätsverbesserungen (v1.1.0):

✨ Scharfe Kanten mit nearest Kernel-Interpolation für QR-Muster
🎯 Hochwertige Logo-Skalierung mit lanczos3 Kernel
📦 PNG-Komprimierungsstufe 6 mit adaptiver Filterung
🖼️ Standardgröße von 300px auf 512px für bessere Klarheit erhöht

Webhook-Tools

`get_webhook_events`

In Echtzeit von der Bitnovo Pay API empfangene Webhook-Ereignisse abfragen.

Verfügbar wenn: WEBHOOK_ENABLED=true

{
  "identifier": "payment_id_here",
  "limit": 50,
  "validated_only": true
}

`get_webhook_url`

Öffentliche Webhook-URL mit Konfigurationsanweisungen für das Bitnovo-Panel abrufen.

Verfügbar wenn: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Tunnel-Verbindungsstatus diagnostizieren (ngrok, zrok oder manuell).

Verfügbar wenn: WEBHOOK_ENABLED=true

{}

📚 Dokumentation

API-Tools-Referenz - Detaillierte Dokumentation für alle MCP-Tools
Anwendungsbeispiele - Praxisnahe Anwendungsbeispiele
Fehlerbehandlung - Fehlercodes und Fehlerbehebung
Webhook-System - Webhook-Konfiguration und Tunnel-Management

🏗️ Entwicklung

Verfügbare Skripte

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

Architektur

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

Der MCP-Server kann zwei Server gleichzeitig ausführen:

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

🔒 Sicherheit

Nur HTTPS - Alle API-Aufrufe verwenden HTTPS
HMAC-Validierung - Webhook-Signaturüberprüfung mit SHA-256
Replay-Angriffsprävention - Nonce-Caching mit 5-minütiger TTL
Datenschutz - Sensible Informationen werden in Protokollen maskiert
Keine Kursdaten - Wechselkurse werden nicht offengelegt, um Ungenauigkeiten zu vermeiden
Zustandsloses Design - Keine lokale Persistenz, Echtzeit-API-Abfragen
Automatische Wiederverbindung - Exponentielles Backoff bis zu 10 Wiederholungen für Tunnel
Gesundheitsüberwachung - Verbindungsüberprüfung alle 60 Sekunden

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe LICENSE-Datei für Details.

🤝 Mitwirken

Forken Sie das Repository
Erstellen Sie Ihren Feature-Branch (git checkout -b feature/amazing-feature)
Committen Sie Ihre Änderungen (git commit -m 'Add amazing feature')
Pushen Sie zum Branch (git push origin feature/amazing-feature)
Öffnen Sie einen Pull Request

📞 Support

Issues: GitHub Issues
Bitnovo-Support: https://www.bitnovo.com/
MCP-Protokoll: https://modelcontextprotocol.io/

🌟 Verwandtes

Model Context Protocol - Offizielle MCP-Spezifikation
Bitnovo Pay - Kryptowährungs-Zahlungsplattform
Bitnovo Pay - Dokumentation - Offizielle Bitnovo Pay-Dokumentation
Bitnovo Pay - Documentación en Español - Offizielle Bitnovo Pay-Dokumentation auf Spanisch
MCP SDK - Offizielles MCP SDK für TypeScript