mcp-server-efi by JoaoLucasAl - MCP Server

Servidor MCP Efí

Servidor Node.js implementando o Model Context Protocol (MCP) para operações das APIs do Efí Bank.

Características

Gestão de cobranças PIX imediatas
Pagamentos e transferências PIX
Operações de devolução PIX
Configuração de webhooks
Saldo da conta e configurações
Gerenciamento de EVP (Chaves Aleatórias)
Tratamento de MED (Mecanismo Especial de Devolução)

Instalação

NPX

npx mcp-server-efi

Docker

docker run -i --rm mcp-server-efi \
  --sandbox=false \
  --client-id=seu_client_id \
  --client-secret=seu_client_secret \
  --certificate=seu_certificado_base64 \
  --validate-mtls=true

Configuração

O servidor requer as seguintes variáveis de ambiente:

sandbox: Defina como "false" para produção ou "true" para ambiente sandbox
client-id: Seu Client ID da aplicação do Efí Bank
client-secret: Seu Client Secret da aplicação do Efí Bank
certificate: Seu certificado do Efí Bank em formato Base64
validate-mtls: Defina como "true" para validar mTLS nos webhooks (opcional, padrão é true)

API

Cobranças PIX Imediatas

pix_create_immediate_charge
- Criar cobrança PIX imediata sem especificar txid
- Gera cobrança com tempo de expiração, valor, chave PIX e informações opcionais do devedor
pix_create_charge
- Criar cobrança PIX imediata com txid específico
- Entrada: txid, detalhes da cobrança (valor, chave PIX, info do devedor, etc.)
pix_update_charge
- Atualizar cobrança existente por txid
- Modificar expiração, info do devedor, valor ou informações adicionais
pix_detail_charge
- Obter detalhes da cobrança por txid
- Retorna informações completas da cobrança incluindo status e detalhes do pagamento
pix_list_charges
- Listar cobranças com opções de filtro
- Filtrar por intervalo de datas, CPF/CNPJ, status e paginação

Pagamentos e Transferências PIX

pix_send
- Enviar pagamento PIX para uma chave PIX ou conta bancária
- Suporte para chave PIX ou detalhes de conta bancária como destino
pix_send_detail
- Obter detalhes do PIX enviado por e2eId
- Retorna informações completas da transação
pix_send_list
- Listar transações PIX enviadas com opções de filtro
- Filtrar por intervalo de datas, status e presença de devolução
pix_qr_code_pay
- Pagar QR Code PIX via API
- Processar pagamentos de QR Code com informações do pagador

Gestão PIX

pix_detail_received
- Obter detalhes do PIX recebido por e2eId
- Retorna informações da transação e devolução
pix_received_list
- Listar transações PIX recebidas
- Filtrar por data, txid, CPF/CNPJ com suporte a paginação
pix_devolution
- Criar devolução PIX (estorno)
- Entrada: e2eId, ID da devolução e valor
pix_detail_devolution
- Obter detalhes da devolução por e2eId e ID da devolução

Webhooks

pix_config_webhook
- Configurar URL do webhook para notificações PIX
- Definir endpoint do webhook para notificações de transação
pix_detail_webhook
- Obter detalhes da configuração do webhook por chave PIX
pix_list_webhook
- Listar todos os webhooks configurados
pix_delete_webhook
- Excluir configuração de webhook por chave PIX
pix_resend_webhook
- Reenviar notificações de webhook para transações específicas

Gestão de Conta

get_account_balance
- Obter saldo atual da conta
- Retorna informações de saldo disponível
update_account_config
- Atualizar configurações PIX da conta
- Configurar definições de chave PIX, restrições e preferências de webhook
list_account_config
- Listar configurações atuais da conta
- Retorna todas as configurações PIX e da conta

Gestão de EVP (Chaves Aleatórias)

pix_create_evp
- Criar nova chave PIX aleatória (EVP)
- Gera chave aleatória para transações PIX
pix_list_evp
- Listar todas as chaves EVP registradas
pix_delete_evp
- Excluir chave EVP específica

MED

med_list
- Listar infrações MED abertas contra a conta
- Filtrar por intervalo de datas com paginação

Funcionalidades Adicionais

pix_get_receipt
- Obter comprovante da transação (formato PDF)
- Gerar comprovante por e2eId, txid ou rtrId

Uso com Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-efi": {
      "command": "npx",
      "args": [
        "mcp-server-efi",
        "--sandbox=false",
        "--client-id=seu_client_id",
        "--client-secret=seu_client_secret",
        "--certificate=seu_certificado_base64",
        "--validate-mtls=true"
      ]
    }
  }
}

Uso com Docker no Claude Desktop

{
  "mcpServers": {
    "mcp-server-efi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp-server-efi",
        "--sandbox=false",
        "--client-id=seu_client_id",
        "--client-secret=seu_client_secret",
        "--certificate=seu_certificado_base64",
        "--validate-mtls=true"
      ]
    }
  }
}

Uso com VS Code

Para instalação manual, adicione o seguinte às configurações do VS Code ou .vscode/mcp.json:

NPX

{
  "mcp": {
    "servers": {
      "mcp-server-efi": {
        "command": "npx",
        "args": [
          "mcp-server-efi",
          "--sandbox=false",
          "--client-id=seu_client_id",
          "--client-secret=seu_client_secret",
          "--certificate=seu_certificado_base64",
          "--validate-mtls=true"
        ]
      }
    }
  }
}

Docker

{
  "mcp": {
    "servers": {
      "mcp-server-efi": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "mcp-server-efi",
          "--sandbox=false",
          "--client-id=seu_client_id",
          "--client-secret=seu_client_secret",
          "--certificate=seu_certificado_base64",
          "--validate-mtls=true"
        ]
      }
    }
  }
}

Build

Desenvolvimento Local

npm install
npm run build
npm start

Build Docker

docker build -t mcp-server-efi .

Notas de Segurança

Sempre use credenciais de produção (sandbox=false) para transações reais
Mantenha seus certificados e credenciais seguros
Habilite a validação mTLS (validate-mtls=true) para segurança do webhook
Todas as chamadas da API são autenticadas usando a implementação OAuth 2.0 do Efí Pay

Suporte

Para documentação e suporte da API do Efí Pay, visite: https://dev.efipay.com.br/