Bitnovo Pay

oficial

Servidor MCP para integração do Bitnovo Pay com agentes de IA. Oferece funcionalidades de pagamento em criptomoedas através da API do Bitnovo Pay. Inclui criação de pagamentos, verificação de status, geração de QR code e gerenciamento de webhooks com suporte a múltiplos provedores de túnel (ngrok, zrok, manual).

GitHub

O que você pode fazer com Bitnovo Pay MCP?

Criar um pagamento cripto on-chain — Peça ao seu assistente para gerar um endereço de criptomoeda para uma moeda específica e valor em euros com create_payment_onchain.
Criar um link de pagamento compartilhável — Solicite que seu assistente construa uma URL de pagamento web onde os clientes escolhem sua criptomoeda via create_payment_link.
Verificar status do pagamento — Consulte o estado atual e os detalhes de qualquer pagamento usando seu identificador com get_payment_status.
Listar moedas suportadas — Recupere criptomoedas disponíveis, opcionalmente filtradas por um valor mínimo em euros, usando list_currencies_catalog.
Gerar um QR de pagamento personalizado — Produza um QR code de alta resolução para um pagamento existente com generate_payment_qr.
Inspecionar eventos de webhook — Consulte notificações de pagamento em tempo real recebidas da Bitnovo via get_webhook_events.

Documentação

MCP Bitnovo Pay

Servidor MCP para integração do Bitnovo Pay com agentes de IA

Um servidor Model Context Protocol (MCP) que fornece a agentes de IA capacidades de pagamento com criptomoedas através da integração com a API Bitnovo Pay. Este servidor permite que modelos de IA criem pagamentos, verifiquem o status de pagamentos, gerenciem códigos QR e acessem catálogos de criptomoedas.

🚀 Funcionalidades

8 Ferramentas MCP para gerenciamento completo de pagamentos:
- create_payment_onchain - Gerar endereços de criptomoedas para pagamentos diretos
- create_payment_link - Criar URLs de pagamento web com tratamento de redirecionamento
- get_payment_status - Consultar status de pagamento com informações detalhadas
- list_currencies_catalog - Obter criptomoedas suportadas com filtragem
- generate_payment_qr - Gerar códigos QR personalizados a partir de pagamentos existentes
- get_webhook_events - Consultar eventos de webhook recebidos em tempo real
- get_webhook_url - Obter URL pública do webhook com instruções de configuração
- get_tunnel_status - Diagnosticar status da conexão do túnel
Sistema Automático de Webhooks com 3 provedores de túnel:
- 🔗 ngrok: URL persistente gratuita (1 domínio estático por conta)
- 🌐 zrok: 100% gratuito e de código aberto com URLs persistentes
- 🏢 manual: Para servidores com IP público (N8N, Opal, VPS)
Suporte Multi-LLM - Compatível com:
- 🤖 OpenAI ChatGPT (GPT-5, GPT-4o, API Responses, Agents SDK)
- 🧠 Google Gemini (Gemini 2.5 Flash/Pro Set 2025, CLI, FastMCP)
- 🔮 Claude (Claude Desktop, Claude Code)
Códigos QR de Alta Qualidade (v1.1.0+):
- 📱 Resolução padrão de 512px (antes 300px) para telas modernas
- 🖨️ Suporte de até 2000px para impressão profissional
- ✨ Bordas nítidas com algoritmos de interpolação otimizados
- 🎨 Marca personalizada Bitnovo Pay com escala suave do logotipo
Privacidade por Padrão - Dados sensíveis mascarados nos logs, exposição mínima de dados
Seguro - Imposição de HTTPS, validação de assinatura HMAC, tratamento seguro de segredos
Confiável - Lógica de repetição integrada, tratamento de timeout, operação sem estado

📋 Pré-requisitos

Node.js 18+
Conta Bitnovo Pay com Device ID e Device Secret opcional
Configuração de Ambiente (consulte os guias de configuração abaixo)

⚡ Início Rápido

1. Obtenha Suas Credenciais Bitnovo

Cadastre-se em Bitnovo Pay
Obtenha seu Device ID no painel Bitnovo
(Opcional) Gere um Device Secret para validação de assinatura de webhook

2. Configure Seu Cliente MCP

Adicione esta configuração ao arquivo de configuração do seu 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 (consulte o Guia de Configuração 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. Reinicie Seu Cliente MCP

Reinicie o Claude Desktop, ChatGPT ou seu cliente MCP para carregar o servidor.

4. Teste a Integração

Pergunte ao seu assistente de IA: "Crie um pagamento de 10 euros"

☁️ Implantação em Nuvem (NOVO na v1.2.0)

O MCP Bitnovo Pay agora suporta implantação remota em plataformas de nuvem com modo de transporte HTTP. Isso permite que plataformas de IA como claude.ai se conectem ao seu servidor MCP remotamente.

Implantar no Railway (Recomendado)

Configuração Rápida:

Clique em "Deploy to Railway" ou crie um novo projeto
Defina as variáveis de ambiente:
- BITNOVO_DEVICE_ID - Seu ID de dispositivo Bitnovo
- BITNOVO_BASE_URL - https://pos.bitnovo.com
Implante (Railway detecta automaticamente o Dockerfile)
Obtenha sua URL pública: https://your-app.up.railway.app

Conectar ao claude.ai:

Adicione o servidor em Configurações → Model Context Protocol
URL do Servidor: https://your-app.up.railway.app/mcp

📖 Guia Completo: Consulte RAILWAY.md para instruções detalhadas de implantação, solução de problemas e configuração.

Implantar no 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

Implantar em Outras Plataformas

O servidor funciona em qualquer plataforma que suporte Node.js e Docker:

Heroku: Envie o Dockerfile com variáveis de ambiente
Fly.io: Implante com configuração fly.toml
Google Cloud Run: Implante contêiner Docker
AWS ECS/Fargate: Implante com definição de tarefa

Variáveis de Ambiente Necessárias:

PORT - Porta HTTP (definida automaticamente pela maioria das plataformas)
BITNOVO_DEVICE_ID - Seu ID de dispositivo Bitnovo
BITNOVO_BASE_URL - URL da API Bitnovo

Detecção do Modo de Transporte:

Se a variável de ambiente PORT estiver definida → modo HTTP (conexões remotas)
Se não houver PORT → modo stdio (conexões locais)

📦 Opções de Instalação

Opção A: Usando npx (Recomendado)

Nenhuma instalação necessária! O comando npx baixa e executa automaticamente a versão mais recente.

npx -y @bitnovopay/mcp-bitnovo-pay

Vantagens:

✅ Sempre obtém a versão mais recente
✅ Sem necessidade de atualizações manuais
✅ Sem necessidade de instalação local
✅ Funciona imediatamente

Opção B: Clonar Repositório (Para Desenvolvimento)

Para contribuidores ou usuários avançados que precisam modificar o 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

Vantagens:

✅ Controle total do código fonte
✅ Capacidade de modificar e testar alterações
✅ Ideal para contribuir com o projeto

🔧 Configuração por Plataforma LLM

Escolha sua plataforma de IA e siga o guia de configuração específico:

Claude Desktop (Anthropic)

Local do Arquivo de Configuração: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) Guia: Guia de Configuração Claude

Configuração 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"
      }
    }
  }
}

Com Webhooks (para notificações de pagamento em tempo 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

Guia: Guia de Configuração OpenAI Suportado: GPT-5, GPT-4o, API Responses, Agents SDK

Configuração 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

Guia: Guia de Configuração Gemini Suportado: Gemini 2.5 Flash/Pro (Set 2025), CLI, FastMCP

Configuração 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"
      }
    }
  }
}

Variáveis de Ambiente

Variável	Obrigatória	Descrição	Exemplo
`BITNOVO_DEVICE_ID`	✅ Sim	Seu identificador de dispositivo Bitnovo Pay	`12345678-abcd-1234-abcd-1234567890ab`
`BITNOVO_BASE_URL`	✅ Sim	Endpoint da API Bitnovo	`https://pos.bitnovo.com` (produção) `https://payments.pre-bnvo.com` (desenvolvimento)
`BITNOVO_DEVICE_SECRET`	⚠️ Opcional	Segredo HMAC para validação de webhook	`your_hex_secret`
`WEBHOOK_ENABLED`	⚠️ Opcional	Habilitar servidor de webhook	`true` ou `false`
`TUNNEL_ENABLED`	⚠️ Opcional	Iniciar túnel automaticamente para webhooks	`true` ou `false`
`TUNNEL_PROVIDER`	⚠️ Opcional	Provedor de túnel	`ngrok`, `zrok` ou `manual`

Nota de Segurança: Nunca faça commit de credenciais no controle de versão. Use variáveis de ambiente ou gerenciamento seguro de segredos.

🛠️ Referência das Ferramentas MCP

Criação de Pagamento

`create_payment_onchain`

Cria um pagamento com criptomoeda com um endereço específico para transações diretas.

Usar quando: O usuário especificar uma criptomoeda (Bitcoin, ETH, USDC, etc.)

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

`create_payment_link`

Cria uma URL de pagamento web onde os clientes podem escolher sua criptomoeda.

Usar quando: Solicitação de pagamento genérica sem menção de criptomoeda específica (OPÇÃO PADRÃO)

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

Gerenciamento de Pagamento

`get_payment_status`

Recupera o status atual do pagamento com informações detalhadas.

{
  "identifier": "payment_id_here"
}

Códigos de Status:

NR (Não Pronto): Pré-pagamento criado, sem criptomoeda atribuída
PE (Pendente): Aguardando pagamento do cliente
AC (Aguardando Conclusão): Criptomoeda detectada na mempool
CO (Concluído): Pagamento confirmado na blockchain
EX (Expirado): Limite de tempo do pagamento excedido
CA (Cancelado): Pagamento cancelado
FA (Falhou): Falha na confirmação da transação

`list_currencies_catalog`

Obtém criptomoedas disponíveis com filtragem opcional por valor.

{
  "filter_by_amount": 25.0
}

`generate_payment_qr`

Cria códigos QR personalizados para pagamentos existentes com saída de alta qualidade.

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

Tipos de QR:

address: Apenas endereço da criptomoeda (cliente insere o valor manualmente)
payment_uri: Endereço + valor incluído (recomendado)
both: Gerar ambos os tipos (recomendado)
gateway_url: QR da URL do gateway de pagamento

Opções de Tamanho do QR (v1.1.0+):

Padrão: 512px (otimizado para telas modernas)
Faixa: 100px - 2000px
Tamanhos recomendados:
- 512px: Telas de dispositivos móveis e web
- 800-1200px: Impressão padrão
- 1600-2000px: Impressão de alta qualidade (pôsteres, displays)

Melhorias de Qualidade (v1.1.0):

✨ Bordas nítidas com interpolação de kernel nearest para padrões QR
🎯 Escala de logotipo de alta qualidade com kernel lanczos3
📦 Compressão PNG nível 6 com filtragem adaptativa
🖼️ Tamanho padrão aumentado de 300px para 512px para melhor clareza

Ferramentas de Webhook

`get_webhook_events`

Consulta eventos de webhook recebidos em tempo real da API Bitnovo Pay.

Disponível quando: WEBHOOK_ENABLED=true

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

`get_webhook_url`

Obtém a URL pública do webhook com instruções de configuração para o painel Bitnovo.

Disponível quando: WEBHOOK_ENABLED=true

{
  "validate": true
}

`get_tunnel_status`

Diagnostica o status da conexão do túnel (ngrok, zrok ou manual).

Disponível quando: WEBHOOK_ENABLED=true

{}

📚 Documentação

Referência de Ferramentas da API - Documentação detalhada de todas as ferramentas MCP
Exemplos de Uso - Exemplos de uso no mundo real
Tratamento de Erros - Códigos de erro e solução de problemas
Sistema de Webhook - Configuração de webhook e gerenciamento de túnel

🏗️ Desenvolvimento

Scripts Disponíveis

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

Arquitetura

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

Arquitetura de Servidor Duplo

O servidor MCP pode executar dois servidores simultaneamente:

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

🔒 Segurança

Apenas HTTPS - Todas as chamadas de API usam HTTPS
Validação HMAC - Verificação de assinatura de webhook com SHA-256
Prevenção de Ataques de Repetição - Cache de nonce com TTL de 5 minutos
Privacidade de Dados - Informações sensíveis são mascaradas nos logs
Sem Dados de Taxa - Taxas de câmbio não expostas para evitar imprecisões
Design Sem Estado - Sem persistência local, consultas à API em tempo real
Reconexão Automática - Backoff exponencial de até 10 tentativas para túneis
Monitoramento de Saúde - Verificação de conexão a cada 60 segundos

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🤝 Contribuindo

Faça um fork do repositório
Crie seu branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit de suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

📞 Suporte

Problemas: GitHub Issues
Suporte Bitnovo: https://www.bitnovo.com/
Protocolo MCP: https://modelcontextprotocol.io/

🌟 Relacionados

Model Context Protocol - Especificação oficial do MCP
Bitnovo Pay - Plataforma de pagamento com criptomoedas
Bitnovo Pay - Documentação - Documentação Oficial do Bitnovo Pay
Bitnovo Pay - Documentación en Español - Documentação Oficial do Bitnovo Pay
MCP SDK - SDK oficial do MCP para TypeScript