Bitnovo Pay MCP Server

officiel

Serveur MCP pour l'intégration de Bitnovo Pay avec des agents IA. Fournit des capacités de paiement en cryptomonnaie via l'API Bitnovo Pay. Fonctionnalités incluant la création de paiements, la vérification de statut, la génération de codes QR et la gestion de webhooks avec prise en charge de plusieurs fournisseurs de tunnel (ngrok, zrok, manuel).

GitHub

Documentation

MCP Bitnovo Pay

Serveur MCP pour l'intégration de Bitnovo Pay avec des agents IA

Un serveur Model Context Protocol (MCP) qui fournit aux agents IA des capacités de paiement en cryptomonnaie via l'intégration de l'API Bitnovo Pay. Ce serveur permet aux modèles IA de créer des paiements, vérifier le statut des paiements, gérer les codes QR et accéder aux catalogues de cryptomonnaies.

🚀 Fonctionnalités

8 outils MCP pour une gestion complète des paiements :
- create_payment_onchain - Générer des adresses de cryptomonnaie pour les paiements directs
- create_payment_link - Créer des URL de paiement web avec gestion de redirection
- get_payment_status - Interroger le statut du paiement avec des informations détaillées
- list_currencies_catalog - Obtenir les cryptomonnaies prises en charge avec filtrage
- generate_payment_qr - Générer des codes QR personnalisés à partir de paiements existants
- get_webhook_events - Interroger les événements webhook reçus en temps réel
- get_webhook_url - Obtenir l'URL publique du webhook avec les instructions de configuration
- get_tunnel_status - Diagnostiquer l'état de la connexion tunnel
Système de Webhook Automatique avec 3 fournisseurs de tunnel :
- 🔗 ngrok : URL persistante gratuite (1 domaine statique par compte)
- 🌐 zrok : 100% gratuit open-source avec URL persistantes
- 🏢 manual : Pour les serveurs avec IP publique (N8N, Opal, VPS)
Support Multi-LLM - Compatible avec :
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, API Responses, SDK Agents)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Sept 2025, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
Codes QR de Haute Qualité (v1.1.0+) :
- 📱 Résolution par défaut de 512px (au lieu de 300px) pour les écrans modernes
- 🖨️ Support jusqu'à 2000px pour l'impression professionnelle
- ✨ Bords nets avec algorithmes d'interpolation optimisés
- 🎨 Marque Bitnovo Pay personnalisée avec mise à l'échelle fluide du logo
Confidentialité par Défaut - Données sensibles masquées dans les logs, exposition minimale des données
Sécurisé - Application HTTPS, validation de signature HMAC, gestion sécurisée des secrets
Fiable - Logique de réessai intégrée, gestion des délais, fonctionnement sans état

📋 Prérequis

Node.js 18+
Compte Bitnovo Pay avec ID de dispositif et Secret de dispositif optionnel
Configuration de l'environnement (voir les guides de configuration ci-dessous)

⚡ Démarrage Rapide

1. Obtenez vos identifiants Bitnovo

Inscrivez-vous sur Bitnovo Pay
Obtenez votre ID de dispositif depuis le tableau de bord Bitnovo
(Optionnel) Générez un Secret de dispositif pour la validation de signature webhook

2. Configurez votre client MCP

Ajoutez cette configuration à votre fichier de configuration client MCP :

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

Pour OpenAI ChatGPT (voir Guide de configuration OpenAI) :

{
  "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. Redémarrez votre client MCP

Redémarrez Claude Desktop, ChatGPT ou votre client MCP pour charger le serveur.

4. Testez l'intégration

Demandez à votre assistant IA : "Créez un paiement de 10 euros"

☁️ Déploiement Cloud (NOUVEAU dans v1.2.0)

MCP Bitnovo Pay prend désormais en charge le déploiement à distance sur des plateformes cloud avec le mode de transport HTTP. Cela permet aux plateformes IA comme claude.ai de se connecter à distance à votre serveur MCP.

Déployer sur Railway (Recommandé)

Configuration rapide :

Cliquez sur "Deploy to Railway" ou créez un nouveau projet
Définissez les variables d'environnement :
- BITNOVO_DEVICE_ID - Votre ID de dispositif Bitnovo
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Déployez (Railway détecte automatiquement le Dockerfile)
Obtenez votre URL publique : https://your-app.up.railway.app

Connexion à claude.ai :

Ajoutez un serveur dans Paramètres → Model Context Protocol
URL du serveur : https://your-app.up.railway.app/mcp

📖 Guide complet : Voir RAILWAY.md pour des instructions de déploiement détaillées, le dépannage et la configuration.

Déployer sur 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

Déployer sur d'autres plateformes

Le serveur fonctionne sur toute plateforme prenant en charge Node.js et Docker :

Heroku : Poussez le Dockerfile avec les variables d'environnement
Fly.io : Déployez avec la configuration fly.toml
Google Cloud Run : Déployez le conteneur Docker
AWS ECS/Fargate : Déployez avec la définition de tâche

Variables d'environnement requises :

PORT - Port HTTP (défini automatiquement par la plupart des plateformes)
BITNOVO_DEVICE_ID - Votre ID de dispositif Bitnovo
BITNOVO_BASE_URL - URL de l'API Bitnovo

Détection du mode de transport :

Si la variable d'env PORT est définie → mode HTTP (connexions à distance)
Si pas de PORT → mode stdio (connexions locales)

📦 Options d'installation

Option A : Utiliser npx (Recommandé)

Aucune installation requise ! La commande npx télécharge et exécute automatiquement la dernière version.

npx -y @bitnovopay/mcp-bitnovo-pay

Avantages :

✅ Toujours la dernière version
✅ Aucune mise à jour manuelle nécessaire
✅ Aucune installation locale requise
✅ Fonctionne immédiatement

Option B : Cloner le dépôt (Pour le développement)

Pour les contributeurs ou les utilisateurs avancés qui ont besoin de modifier le 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

Avantages :

✅ Contrôle total du code source
✅ Possibilité de modifier et tester les changements
✅ Idéal pour contribuer au projet

🔧 Configuration par plateforme LLM

Choisissez votre plateforme IA et suivez le guide de configuration spécifique :

Claude Desktop (Anthropic)

Emplacement du fichier de configuration : ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Guide : Guide de configuration Claude

Configuration de base :

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

Avec Webhooks (pour les notifications de paiement en temps réel) :

{
  "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 : Guide de configuration OpenAI Supporté : GPT-5, GPT-4o, API Responses, SDK Agents

Configuration de base :

{
  "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 : Guide de configuration Gemini Supporté : Gemini 2.5 Flash/Pro (Sept 2025), CLI, FastMCP

Configuration de base :

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

Variables d'environnement

Variable	Requis	Description	Exemple
`BITNOVO_DEVICE_ID`	✅ Oui	Votre identifiant de dispositif Bitnovo Pay	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ Oui	Point de terminaison API Bitnovo	`https://pos.bitnovo.com` (production) `https://payments.pre-bnvo.com` (développement)
`BITNOVO_DEVICE_SECRET`	⚠️ Optionnel	Secret HMAC pour la validation webhook	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ Optionnel	Activer le serveur webhook	`true` ou `false`
`TUNNEL_ENABLED`	⚠️ Optionnel	Démarrer automatiquement le tunnel pour les webhooks	`true` ou `false`
`TUNNEL_PROVIDER`	⚠️ Optionnel	Fournisseur de tunnel	`ngrok`, `zrok`, ou `manual`

Note de sécurité : Ne jamais valider les identifiants dans le contrôle de version. Utilisez des variables d'environnement ou une gestion sécurisée des secrets.

🛠️ Référence des outils MCP

Création de paiement

`create_payment_onchain`

Crée un paiement en cryptomonnaie avec une adresse spécifique pour les transactions directes.

Utiliser quand : L'utilisateur spécifie une cryptomonnaie (Bitcoin, ETH, USDC, etc.)

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

`create_payment_link`

Crée une URL de paiement web où les clients peuvent choisir leur cryptomonnaie.

Utiliser quand : Demande de paiement générique sans crypto spécifique mentionnée (OPTION PAR DÉFAUT)

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

Gestion des paiements

`get_payment_status`

Récupère le statut actuel du paiement avec des informations détaillées.

{
  "identifier": "payment_id_here"
}

Codes de statut :

NR (Pas prêt) : Pré-paiement créé, aucune crypto assignée
PE (En attente) : En attente du paiement du client
AC (En attente de complétion) : Crypto détectée dans le mempool
CO (Complété) : Paiement confirmé sur la blockchain
EX (Expiré) : Limite de temps de paiement dépassée
CA (Annulé) : Paiement annulé
FA (Échoué) : La transaction n'a pas pu être confirmée

`list_currencies_catalog`

Obtient les cryptomonnaies disponibles avec filtrage optionnel par montant.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

Crée des codes QR personnalisés pour les paiements existants avec une sortie de haute qualité.

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

Types de QR :

address : Adresse crypto uniquement (le client saisit le montant manuellement)
payment_uri : Adresse + montant inclus (recommandé)
both : Générer les deux types (recommandé)
gateway_url : QR de l'URL de la passerelle de paiement

Options de taille QR (v1.1.0+) :

Par défaut : 512px (optimisé pour les écrans modernes)
Plage : 100px - 2000px
Tailles recommandées :
- 512px : Affichages mobiles et web
- 800-1200px : Impression standard
- 1600-2000px : Impression haute qualité (affiches, présentoirs)

Améliorations de qualité (v1.1.0) :

✨ Bords nets avec interpolation par noyau nearest pour les motifs QR
🎯 Mise à l'échelle du logo de haute qualité avec noyau lanczos3
📦 Niveau de compression PNG 6 avec filtrage adaptatif
🖼️ Taille par défaut augmentée de 300px à 512px pour une meilleure clarté

Outils Webhook

`get_webhook_events`

Interroger les événements webhook reçus en temps réel depuis l'API Bitnovo Pay.

Disponible quand : WEBHOOK_ENABLED=true

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

`get_webhook_url`

Obtenir l'URL publique du webhook avec les instructions de configuration pour le panneau Bitnovo.

Disponible quand : WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Diagnostiquer l'état de la connexion tunnel (ngrok, zrok, ou manual).

Disponible quand : WEBHOOK_ENABLED=true

{}

📚 Documentation

Référence des outils API - Documentation détaillée pour tous les outils MCP
Exemples d'utilisation - Exemples d'utilisation réels
Gestion des erreurs - Codes d'erreur et dépannage
Système Webhook - Configuration webhook et gestion des tunnels

🏗️ Développement

Scripts disponibles

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/)    │
└─────────────────┘

Architecture double serveur

Le serveur MCP peut exécuter deux serveurs simultanément :

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

🔒 Sécurité

HTTPS uniquement - Tous les appels API utilisent HTTPS
Validation HMAC - Vérification de signature webhook avec SHA-256
Prévention des attaques par rejeu - Mise en cache des nonces avec TTL de 5 minutes
Confidentialité des données - Les informations sensibles sont masquées dans les logs
Pas de données de taux - Les taux de change ne sont pas exposés pour éviter les inexactitudes
Conception sans état - Pas de persistance locale, requêtes API en temps réel
Reconnexion automatique - Backoff exponentiel jusqu'à 10 réessais pour les tunnels
Surveillance de santé - Vérification de connexion toutes les 60 secondes

📄 Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

🤝 Contribuer

Forker le dépôt
Créer votre branche de fonctionnalité (git checkout -b feature/amazing-feature)
Valider vos modifications (git commit -m 'Add amazing feature')
Pousser vers la branche (git push origin feature/amazing-feature)
Ouvrir une Pull Request

📞 Support

Problèmes : GitHub Issues
Support Bitnovo : https://www.bitnovo.com/
Protocole MCP : https://modelcontextprotocol.io/

🌟 Liens connexes

Model Context Protocol - Spécification officielle MCP
Bitnovo Pay - Plateforme de paiement en cryptomonnaie
Bitnovo Pay - Documentation - Documentation officielle Bitnovo Pay
Bitnovo Pay - Documentación en Español - Documentación Oficial de Bitnovo Pay
SDK MCP - SDK MCP officiel pour TypeScript