Bitnovo Pay

oficial

Servidor MCP para la integración de Bitnovo Pay con agentes de IA. Proporciona capacidades de pago con criptomonedas a través de la API de Bitnovo Pay. Las funciones incluyen creación de pagos, verificación de estado, generación de códigos QR y gestión de webhooks con soporte para múltiples proveedores de túneles (ngrok, zrok, manual).

GitHub

¿Qué puedes hacer con Bitnovo Pay MCP?

Crear un pago cripto en cadena — Pídele a tu asistente que genere una dirección de criptomoneda para una moneda y un monto en euros específicos con create_payment_onchain.
Crear un enlace de pago compartible — Haz que tu asistente construya una URL de pago web donde los clientes elijan su criptomoneda mediante create_payment_link.
Verificar el estado del pago — Solicita el estado actual y los detalles de cualquier pago usando su identificador con get_payment_status.
Listar monedas compatibles — Recupera las criptomonedas disponibles, opcionalmente filtradas por un monto mínimo en euros, usando list_currencies_catalog.
Generar un código QR de pago personalizado — Produce un código QR de alta resolución para un pago existente con generate_payment_qr.
Inspeccionar eventos de webhook — Consulta las notificaciones de pago en tiempo real recibidas de Bitnovo mediante get_webhook_events.

Documentación

MCP Bitnovo Pay

Servidor MCP para integración de Bitnovo Pay con agentes de IA

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona a los agentes de IA capacidades de pago con criptomonedas mediante la integración con la API de Bitnovo Pay. Este servidor permite a los modelos de IA crear pagos, verificar el estado de los pagos, gestionar códigos QR y acceder a catálogos de criptomonedas.

🚀 Características

8 herramientas MCP para una gestión integral de pagos:
- create_payment_onchain - Generar direcciones de criptomonedas para pagos directos
- create_payment_link - Crear URLs de pago web con manejo de redirecciones
- get_payment_status - Consultar el estado del pago con información detallada
- list_currencies_catalog - Obtener criptomonedas admitidas con filtrado
- generate_payment_qr - Generar códigos QR personalizados a partir de pagos existentes
- get_webhook_events - Consultar eventos de webhook recibidos en tiempo real
- get_webhook_url - Obtener la URL pública del webhook con instrucciones de configuración
- get_tunnel_status - Diagnosticar el estado de la conexión del túnel
Sistema automático de Webhooks con 3 proveedores de túnel:
- 🔗 ngrok: URL persistente gratuita (1 dominio estático por cuenta)
- 🌐 zrok: 100% gratuito y de código abierto con URLs persistentes
- 🏢 manual: Para servidores con IP pública (N8N, Opal, VPS)
Soporte Multi-LLM - Compatible con:
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, API de Respuestas, SDK de Agentes)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Sept 2025, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
Códigos QR de alta calidad (v1.1.0+):
- 📱 Resolución predeterminada de 512px (antes 300px) para pantallas modernas
- 🖨️ Soporte de hasta 2000px para impresión profesional
- ✨ Bordes nítidos con algoritmos de interpolación optimizados
- 🎨 Marca personalizada de Bitnovo Pay con escalado suave del logotipo
Privacidad por defecto - Datos sensibles enmascarados en los registros, exposición mínima de datos
Seguro - Aplicación de HTTPS, validación de firma HMAC, manejo seguro de secretos
Fiable - Lógica de reintento incorporada, manejo de tiempos de espera, funcionamiento sin estado

📋 Requisitos previos

Node.js 18+
Cuenta de Bitnovo Pay con ID de dispositivo y Secreto de dispositivo opcional
Configuración del entorno (consulta las guías de configuración a continuación)

⚡ Inicio rápido

1. Obtén tus credenciales de Bitnovo

Regístrate en Bitnovo Pay
Obtén tu ID de dispositivo desde el panel de Bitnovo
(Opcional) Genera un Secreto de dispositivo para la validación de firma del webhook

2. Configura tu cliente MCP

Añade esta configuración al archivo de configuración de tu cliente MCP:

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

Para OpenAI ChatGPT (consulta la Guía de configuración de 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. Reinicia tu cliente MCP

Reinicia Claude Desktop, ChatGPT o tu cliente MCP para cargar el servidor.

4. Prueba la integración

Pregunta a tu asistente de IA: "Crea un pago por 10 euros"

☁️ Despliegue en la nube (NUEVO en v1.2.0)

MCP Bitnovo Pay ahora admite el despliegue remoto en plataformas en la nube con modo de transporte HTTP. Esto permite que plataformas de IA como claude.ai se conecten a tu servidor MCP de forma remota.

Desplegar en Railway (Recomendado)

Configuración rápida:

Haz clic en "Deploy to Railway" o crea un nuevo proyecto
Establece las variables de entorno:
- BITNOVO_DEVICE_ID - Tu ID de dispositivo de Bitnovo
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Despliega (Railway detecta automáticamente el Dockerfile)
Obtén tu URL pública: https://your-app.up.railway.app

Conectar a claude.ai:

Añade el servidor en Configuración → Protocolo de Contexto de Modelo
URL del servidor: https://your-app.up.railway.app/mcp

📖 Guía completa: Consulta RAILWAY.md para instrucciones detalladas de despliegue, solución de problemas y configuración.

Desplegar en 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

Desplegar en otras plataformas

El servidor funciona en cualquier plataforma que admita Node.js y Docker:

Heroku: Sube el Dockerfile con variables de entorno
Fly.io: Despliega con configuración de fly.toml
Google Cloud Run: Despliega el contenedor Docker
AWS ECS/Fargate: Despliega con definición de tarea

Variables de entorno requeridas:

PORT - Puerto HTTP (autoestablecido por la mayoría de las plataformas)
BITNOVO_DEVICE_ID - Tu ID de dispositivo de Bitnovo
BITNOVO_BASE_URL - URL de la API de Bitnovo

Detección del modo de transporte:

Si la variable de entorno PORT está establecida → modo HTTP (conexiones remotas)
Si no hay PORT → modo stdio (conexiones locales)

📦 Opciones de instalación

Opción A: Usando npx (Recomendado)

¡No requiere instalación! El comando npx descarga y ejecuta automáticamente la última versión.

npx -y @bitnovopay/mcp-bitnovo-pay

Ventajas:

✅ Obtienes siempre la última versión
✅ No se necesitan actualizaciones manuales
✅ No requiere instalación local
✅ Funciona de inmediato

Opción B: Clonar el repositorio (Para desarrollo)

Para colaboradores o usuarios avanzados que necesiten modificar el código:

# 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

Ventajas:

✅ Control total del código fuente
✅ Capacidad para modificar y probar cambios
✅ Ideal para contribuir al proyecto

🔧 Configuración por plataforma LLM

Elige tu plataforma de IA y sigue la guía de configuración específica:

Claude Desktop (Anthropic)

Ubicación del archivo de configuración: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Guía: Guía de configuración de Claude

Configuración básica:

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

Con Webhooks (para notificaciones de pago en tiempo real):

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

Guía: Guía de configuración de OpenAI Compatible: GPT-5, GPT-4o, API de Respuestas, SDK de Agentes

Configuración básica:

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

Guía: Guía de configuración de Gemini Compatible: Gemini 2.5 Flash/Pro (Sept 2025), CLI, FastMCP

Configuración básica:

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

Variable	Requerida	Descripción	Ejemplo
`BITNOVO_DEVICE_ID`	✅ Sí	Tu identificador de dispositivo de Bitnovo Pay	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ Sí	Endpoint de la API de Bitnovo	`https://pos.bitnovo.com` (producción) `https://payments.pre-bnvo.com` (desarrollo)
`BITNOVO_DEVICE_SECRET`	⚠️ Opcional	Secreto HMAC para validación del webhook	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ Opcional	Habilitar servidor de webhooks	`true` o `false`
`TUNNEL_ENABLED`	⚠️ Opcional	Iniciar túnel automáticamente para webhooks	`true` o `false`
`TUNNEL_PROVIDER`	⚠️ Opcional	Proveedor de túnel	`ngrok`, `zrok` o `manual`

Nota de seguridad: Nunca incluyas credenciales en el control de versiones. Usa variables de entorno o gestión segura de secretos.

🛠️ Referencia de herramientas MCP

Creación de pagos

`create_payment_onchain`

Crea un pago con criptomonedas con una dirección específica para transacciones directas.

Usar cuando: El usuario especifica una criptomoneda (Bitcoin, ETH, USDC, etc.)

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

`create_payment_link`

Crea una URL de pago web donde los clientes pueden elegir su criptomoneda.

Usar cuando: Solicitud de pago genérica sin criptomoneda específica mencionada (OPCIÓN POR DEFECTO)

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

Gestión de pagos

`get_payment_status`

Recupera el estado actual del pago con información detallada.

{
  "identifier": "payment_id_here"
}

Códigos de estado:

NR (No listo): Prepago creado, sin criptomoneda asignada
PE (Pendiente): Esperando el pago del cliente
AC (Esperando finalización): Criptomoneda detectada en mempool
CO (Completado): Pago confirmado en la blockchain
EX (Expirado): Límite de tiempo de pago excedido
CA (Cancelado): Pago cancelado
FA (Fallido): La transacción no se pudo confirmar

`list_currencies_catalog`

Obtiene las criptomonedas disponibles con filtrado opcional basado en el monto.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

Crea códigos QR personalizados para pagos existentes con salida de alta calidad.

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

Tipos de QR:

address: Solo dirección de criptomoneda (el cliente ingresa el monto manualmente)
payment_uri: Dirección + monto incluido (recomendado)
both: Generar ambos tipos (recomendado)
gateway_url: QR de la URL de la pasarela de pago

Opciones de tamaño de QR (v1.1.0+):

Predeterminado: 512px (optimizado para pantallas modernas)
Rango: 100px - 2000px
Tamaños recomendados:
- 512px: Pantallas móviles y web
- 800-1200px: Impresión estándar
- 1600-2000px: Impresión de alta calidad (pósteres, stands)

Mejoras de calidad (v1.1.0):

✨ Bordes nítidos con interpolación de kernel nearest para patrones QR
🎯 Escalado de logotipo de alta calidad con kernel lanczos3
📦 Nivel de compresión PNG 6 con filtrado adaptativo
🖼️ Tamaño predeterminado aumentado de 300px a 512px para mayor claridad

Herramientas de Webhook

`get_webhook_events`

Consulta los eventos de webhook recibidos en tiempo real desde la API de Bitnovo Pay.

Disponible cuando: WEBHOOK_ENABLED=true

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

`get_webhook_url`

Obtiene la URL pública del webhook con instrucciones de configuración para el panel de Bitnovo.

Disponible cuando: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Diagnostica el estado de la conexión del túnel (ngrok, zrok o manual).

Disponible cuando: WEBHOOK_ENABLED=true

{}

📚 Documentación

Referencia de herramientas API - Documentación detallada de todas las herramientas MCP
Ejemplos de uso - Ejemplos de uso en el mundo real
Manejo de errores - Códigos de error y solución de problemas
Sistema de Webhooks - Configuración de webhooks y gestión de túneles

🏗️ Desarrollo

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

Arquitectura

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

Arquitectura de doble servidor

El servidor MCP puede ejecutar dos servidores simultáneamente:

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

🔒 Seguridad

Solo HTTPS - Todas las llamadas a la API usan HTTPS
Validación HMAC - Verificación de firma de webhook con SHA-256
Prevención de ataques de repetición - Caché de nonce con TTL de 5 minutos
Privacidad de datos - La información sensible se enmascara en los registros
Sin datos de tasa - Las tasas de cambio no se exponen para evitar inexactitudes
Diseño sin estado - Sin persistencia local, consultas a la API en tiempo real
Reconexión automática - Retroceso exponencial de hasta 10 reintentos para túneles
Monitorización de salud - Verificación de conexión cada 60 segundos

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🤝 Contribuir

Haz un fork del repositorio
Crea tu rama de funcionalidad (git checkout -b feature/amazing-feature)
Confirma tus cambios (git commit -m 'Add amazing feature')
Sube a la rama (git push origin feature/amazing-feature)
Abre una Pull Request

📞 Soporte

Incidencias: GitHub Issues
Soporte de Bitnovo: https://www.bitnovo.com/
Protocolo MCP: https://modelcontextprotocol.io/

🌟 Relacionado

Protocolo de Contexto de Modelo - Especificación oficial de MCP
Bitnovo Pay - Plataforma de pagos con criptomonedas
Bitnovo Pay - Documentación - Documentación oficial de Bitnovo Pay
Bitnovo Pay - Documención en Español - Bitnovo Pay Documentación Oficial
MCP SDK - SDK oficial de MCP para TypeScript