N8N Mercado Pago MCP Node

⚠️ VERSÃO BETA - Este projeto está em fase de testes e desenvolvimento ativo. Algumas funcionalidades podem estar instáveis ou incompletas.

Nó customizado do N8N para integração com o MCP Server do Mercado Pago.

Funcionalidades

🔍 Busca na Documentação

• Integração MCP: Conecta-se ao MCP Server para buscar informações na documentação do Mercado Pago
• Múltiplos Idiomas: Suporte para consultas em português, inglês e espanhol
• Busca Inteligente: Utiliza IA para encontrar informações relevantes

💳 Operações de Pagamento

• Criar Pagamento: Cria novos pagamentos com diferentes métodos
• Consultar Pagamento: Busca detalhes de pagamentos existentes
• Cancelar Pagamento: Cancela pagamentos pendentes
• Buscar Pagamentos: Lista e filtra pagamentos

👥 Gerenciamento de Clientes

• Criar Cliente: Registra novos clientes na plataforma
• Buscar Cliente: Consulta informações de clientes existentes
• Atualizar Cliente: Modifica dados de clientes
• Listar Clientes: Busca e filtra clientes

🛒 Preferências de Checkout

• Criar Preferência: Configura checkout personalizado
• Consultar Preferência: Busca configurações de checkout
• Atualizar Preferência: Modifica preferências existentes

🔔 Webhooks e Notificações

• Gerenciar Webhooks: Cria, atualiza e remove webhooks
• Processar Notificações: Processa notificações recebidas
• Eventos em Tempo Real: Monitora pagamentos e pedidos

🤖 Integração MCP (Model Context Protocol)

• MCP Server: Expõe todas as funcionalidades como servidor MCP
• Agentes de IA: Compatível com Claude, ChatGPT, Cursor, Windsurf
• Ferramentas para IA: 15+ ferramentas MCP para automação
• Automação Inteligente: Processamento de linguagem natural
• Workflows MCP: Exemplos prontos para uso

🛡️ Recursos Avançados

• Autenticação Segura: Configuração segura com Access Token
• Ambientes Múltiplos: Suporte para Sandbox e Produção
• Tratamento de Erros: Gerenciamento robusto de erros
• Testes Automatizados: Suite completa de testes unitários
• Documentação Completa: Exemplos de uso e configuração detalhada

🚀 Modos de Uso

1. Nó N8N Tradicional

Use diretamente no N8N para automação de workflows.

2. MCP Server para Agentes de IA

Expõe todas as funcionalidades para agentes de IA via protocolo MCP.

📖 Guia Completo de Integração MCP

Instalação

1. Via NPM (Recomendado)

npm install n8n-nodes-mercadopago-mcp

2. Instalação Manual

1. Clone este repositório
2. Execute pnpm install
3. Execute pnpm build
4. Copie a pasta dist para o diretório de nós customizados do N8N

Configuração

1. Credenciais

1. No N8N, vá em Credentials > Add Credential
2. Selecione Mercado Pago MCP API
3. Preencha:
   • Access Token: Seu token de acesso do Mercado Pago
   • Environment: Sandbox ou Production

2. Como obter o Access Token

1. Acesse Mercado Pago Developers
2. Vá em Suas integrações > Detalhes da aplicação
3. Copie o Access Token de teste ou produção

Uso

Buscar na Documentação

1. Adicione o nó Mercado Pago MCP ao seu workflow
2. Configure:
   • Resource: Documentation
   • Operation: Search
   • Query: Termo de busca (ex: "Como integrar Checkout Pro")
   • Language: Idioma da busca (pt, en, es)
3. Execute o workflow

Exemplos de Uso

🔍 Busca na Documentação

{
  "resource": "Documentation",
  "operation": "Search",
  "query": "Como criar um pagamento PIX?"
}

💳 Criar Pagamento

{
  "resource": "Payment",
  "operation": "Create",
  "amount": 100.50,
  "description": "Produto XYZ",
  "paymentMethodId": "pix",
  "payerEmail": "[email protected]"
}

👥 Criar Cliente

{
  "resource": "Customer",
  "operation": "Create",
  "email": "[email protected]",
  "firstName": "João",
  "lastName": "Silva"
}

🛒 Criar Preferência de Checkout

{
  "resource": "Preference",
  "operation": "Create",
  "items": [
    {
      "title": "Produto A",
      "quantity": 1,
      "unit_price": 75.50
    }
  ]
}

🔔 Configurar Webhook

{
  "resource": "Webhook",
  "operation": "Create",
  "url": "https://meusite.com/webhook",
  "events": ["payment"]
}

Exemplo de Resposta

{
  "query": "Como integrar Checkout Pro",
  "language": "pt",
  "result": {
    "content": "Para integrar o Checkout Pro...",
    "documentation_url": "https://www.mercadopago.com.br/developers/..."
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Casos de Uso

🤖 Automação de Pagamentos

• E-commerce: Automatize criação e processamento de pagamentos
• Assinaturas: Gerencie pagamentos recorrentes
• Marketplace: Processe pagamentos de múltiplos vendedores

📊 Gestão de Clientes

• CRM Integration: Sincronize dados de clientes
• Segmentação: Organize clientes por critérios específicos
• Comunicação: Automatize notificações personalizadas

🔄 Processamento de Webhooks

• Atualizações em Tempo Real: Processe eventos instantaneamente
• Reconciliação: Mantenha dados sincronizados
• Notificações: Envie alertas baseados em eventos

📚 Assistente de Documentação

• Busca Inteligente: Encontre informações rapidamente
• Geração de Código: Obtenha exemplos para diferentes cenários
• Suporte Técnico: Resolva problemas com IA

📈 Monitoramento e Analytics

• Dashboards: Crie painéis de controle personalizados
• Relatórios: Gere relatórios automatizados
• Alertas: Configure notificações baseadas em métricas

🔐 Segurança

⚠️ IMPORTANTE: Este projeto lida com credenciais sensíveis do Mercado Pago.

🚨 Dados Sensíveis a Proteger

Nunca exponha publicamente:

1. Access Token do Mercado Pago

   • Tokens de produção e sandbox
   • Chaves de API

2. Credenciais de Autenticação MCP

   • Usuário e senha para autenticação básica
   • Tokens de acesso

3. URLs de Webhook

   • Endereços de servidor N8N
   • Endpoints privados

4. Dados de Configuração

   • Arquivos .env
   • Configurações do Claude Desktop
   • Workflows do N8N com credenciais

🛡️ Boas Práticas

Variáveis de Ambiente

# ✅ CORRETO - Use variáveis de ambiente
MERCADOPAGO_ACCESS_TOKEN=seu_token_aqui
MCP_AUTH_PASSWORD=senha_segura

# ❌ ERRADO - Nunca hardcode no código
const token = "APP_USR-1234567890-abcdef";

Arquivos de Configuração

// ✅ CORRETO - Use placeholders
{
  "env": {
    "MCP_AUTH_PASSWORD": "sua-senha",
    "MERCADOPAGO_ACCESS_TOKEN": "seu-token"
  }
}

Controle de Versão

• ✅ Arquivos sensíveis protegidos pelo .gitignore
• ✅ Use tokens de sandbox para desenvolvimento
• ✅ Revogue tokens comprometidos imediatamente
• ❌ Nunca commite credenciais reais
• ❌ Nunca exponha tokens em logs

🚨 Se Dados Foram Expostos

1. Tokens Comprometidos:

   • Acesse o painel do Mercado Pago
   • Revogue o token imediatamente
   • Gere um novo token
   • Atualize todas as configurações

2. Dados no Git:

   # Remove do histórico
   git filter-branch --force --index-filter \
     'git rm --cached --ignore-unmatch arquivo-sensivel.json' \
     --prune-empty --tag-name-filter cat -- --all

✅ Checklist de Segurança

• [ ] Tokens em variáveis de ambiente
• [ ] Arquivos sensíveis no .gitignore
• [ ] Configurações usam placeholders
• [ ] HTTPS em todas as conexões
• [ ] Tokens de sandbox para desenvolvimento
• [ ] Monitoramento de acesso ativo

🔗 Integração MCP (Model Context Protocol)

Visão Geral

Este nó funciona como um MCP Server completo, permitindo que agentes de IA (Claude, ChatGPT, etc.) executem operações reais da API do Mercado Pago.

Arquitetura:

Agente IA (Claude/ChatGPT) → MCP Client → N8N MCP Server → Nó Mercado Pago → API Mercado Pago

🛠️ Configuração do MCP Server

1. Importar Workflow MCP Server

1. Abra seu N8N
2. Importe o arquivo examples/mcp-server-workflow.json
3. Configure suas credenciais do Mercado Pago
4. Ative o workflow

2. Configurar Autenticação

O MCP Server usa autenticação básica:

• Username: Defina um usuário
• Password: Defina uma senha segura
• URL: https://seu-n8n.com/webhook/mercadopago-mcp

🔧 Configuração para Claude Desktop

Localizar Arquivo de Configuração:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Adicionar Configuração:

{
  "mcpServers": {
    "mercadopago-n8n": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-remote",
        "https://SEU-N8N.com/webhook/mercadopago-mcp"
      ],
      "env": {
        "MCP_AUTH_USERNAME": "seu-usuario",
        "MCP_AUTH_PASSWORD": "sua-senha"
      }
    }
  }
}

🛠️ Ferramentas MCP Disponíveis

💳 Pagamentos

• mercadopago_payment_create - Criar pagamento
• mercadopago_payment_get - Consultar pagamento
• mercadopago_payment_cancel - Cancelar pagamento

📦 Pedidos

• mercadopago_order_create - Criar pedido
• mercadopago_order_capture - Capturar pedido
• mercadopago_order_get - Consultar pedido
• mercadopago_order_cancel - Cancelar pedido
• mercadopago_order_refund - Reembolsar pedido

👥 Clientes

• mercadopago_customer_create - Criar cliente
• mercadopago_customer_search - Buscar cliente
• mercadopago_customer_update - Atualizar cliente

⚙️ Outras Ferramentas

• mercadopago_preference_create - Criar preferência de checkout
• mercadopago_webhook_create - Criar webhook
• mercadopago_webhook_list - Listar webhooks
• mercadopago_notification_get - Consultar notificação
• mercadopago_documentation_search - Buscar na documentação

💡 Exemplos de Uso com IA

Criar Pagamento

Prompt: "Crie um pagamento de R$ 150,00 para o produto 'Curso de Python' usando PIX"

Resultado:

• IA usa mercadopago_payment_create
• Retorna link de pagamento
• Fornece QR Code PIX

Consultar Status

Prompt: "Verifique o status do pagamento ID 123456789"

Resultado:

• IA usa mercadopago_payment_get
• Retorna status atual
• Informa detalhes do pagamento

Assistente de E-commerce

Prompt: "Preciso processar uma venda de R$ 299 para o cliente [email protected]"

IA executa automaticamente:

1. Busca cliente por email
2. Se não existir, cria novo cliente
3. Cria pagamento com os dados
4. Retorna link de pagamento
5. Configura webhook para notificações

🔍 Troubleshooting MCP

Erro de Conexão

• ✅ Verificar URL do webhook N8N
• ✅ Confirmar autenticação (usuário/senha)
• ✅ Testar conectividade de rede
• ✅ Verificar se workflow está ativo

Erro de Autenticação

• ✅ Verificar credenciais do Mercado Pago
• ✅ Confirmar token de acesso válido
• ✅ Verificar permissões da aplicação

Desenvolvimento

Estrutura do Projeto

├── credentials/
│   └── MercadoPagoMcpApi.credentials.ts
├── nodes/
│   └── MercadoPagoMcp/
│       ├── MercadoPagoMcp.node.ts
│       └── mercadopago.svg
├── package.json
├── tsconfig.json
└── gulpfile.js

Scripts Disponíveis

# Desenvolvimento
pnpm dev          # Watch mode
pnpm build        # Build completo
pnpm lint         # Verificar código
pnpm test         # Executar testes

Limitações

• Atualmente suporta apenas a ferramenta search-documentation
• Requer Access Token válido do Mercado Pago
• MCP Server do Mercado Pago está em fase beta

Roadmap

• [ ] Suporte a mais ferramentas MCP
• [ ] Cache de respostas
• [ ] Métricas de uso
• [ ] Testes automatizados

Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

💝 Apoie o Projeto

Se este projeto te ajudou, considere fazer uma doação PIX para apoiar o desenvolvimento:

PIX para Doações

Chave PIX: [email protected]
Nome: Georgivan Costa

QR Code PIX:

Sua contribuição ajuda a manter este projeto ativo e em constante evolução! 🚀

👨‍💻 Autor

Georgivan Costa - Especialista em Automações com IA

• 📺 YouTube: https://www.youtube.com/@GeorgivanCosta
• 📱 Instagram: https://www.instagram.com/georgivancosta

Siga para mais conteúdo sobre automações, IA e desenvolvimento!

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Suporte

• Documentação do Mercado Pago MCP
• Documentação do N8N
• Issues do GitHub