@integrobr/mcp-server

Servidor MCP da IntegroBR. Deixa um agente de IA (Claude Desktop, Claude Code, ou qualquer cliente que fale MCP) consultar as notas fiscais que a IntegroBR monitora pro CNPJ do cliente, sem abrir o painel e sem escrever código.

Perguntas que ele passa a responder sozinho: "quanto entrou de nota esse mês", "algum fornecedor parou de faturar", "quanto já usei da franquia do plano", "me mostra as notas acima de R$ 5.000 de agosto".

Somente leitura, e isso é deliberado

A API pública da IntegroBR tem endpoints de escrita: criar empresa, subir certificado, pausar, retomar, remover. Nenhum deles é exposto aqui.

O motivo é que um servidor MCP entrega as ferramentas a um modelo que decide sozinho quando chamá-las, a partir de texto que pode vir de qualquer lugar, inclusive do conteúdo de um documento fiscal que a própria ferramenta trouxe. "Remover empresa" nessa posição é risco sem contrapartida. Quem precisa automatizar escrita usa a API direto, com código que passa por revisão.

Todo acesso passa por uma única função que só faz GET. Uma ferramenta nova que precisasse de POST teria que mudar essa função, o que é exatamente o atrito desejado.

Configuração

Gere uma chave de API no painel, em Chaves de API. Recomendado: uma chave dedicada pro agente, de preferência restrita a uma empresa. Assim dá pra revogar o acesso do agente sem derrubar a integração do ERP.

No claude_desktop_config.json:

{
  "mcpServers": {
    "integrobr": {
      "command": "npx",
      "args": ["-y", "@integrobr/mcp-server"],
      "env": { "INTEGROBR_API_KEY": "ibr_live_..." }
    }
  }
}

Variáveis:

| Variável | Obrigatória | Padrão | |---|---|---| | INTEGROBR_API_KEY | sim | — | | INTEGROBR_API_URL | não | https://api.recebidas.integrobr.com/api/v1 |

Uma chave de sandbox (ibr_test_...) funciona igual e não toca em dado de produção. É o jeito seguro de experimentar.

Ferramentas

| Ferramenta | O que faz | |---|---| | consultar_conta | Nome, status e ambiente da conta ligada à chave | | consultar_consumo | Franquia usada no ciclo, saldo e excedente | | listar_empresas | CNPJs monitorados e o estado de cada um | | detalhar_empresa | Detalhe de um CNPJ, incluindo certificado | | listar_documentos | NFS-e, NF-e e CT-e capturadas, com filtro de período, fornecedor, valor, tipo e papel | | detalhar_documento | Documento completo, com prestador, tomador, valores e tributos |

Valores em listar_documentos são filtrados em centavos: R$ 1.500,00 é 150000. A descrição da ferramenta já avisa isso ao modelo.

Desenvolvimento

npm install -w packages/mcp-server
npm run build -w packages/mcp-server

Para testar sem cliente MCP, converse com ele por stdio:

{
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}'
  sleep 1
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  sleep 1
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
  sleep 2
} | INTEGROBR_API_KEY=ibr_live_... node packages/mcp-server/dist/index.js

Cuidado ao mexer: nunca escreva em stdout. Ele é o canal do protocolo, e um console.log solto corrompe a sessão do cliente. Log vai em stderr.