brasilnfe-mcp

<div align="center">

<picture> <source media="(prefers-color-scheme: dark)" srcset="./assets/logo-brasilnfe-branca.png"> <img src="./assets/logo-brasilnfe.png" alt="Brasil NFe" width="320"> </picture>

Brasil NFe MCP

Servidor MCP fiscal brasileiro - sua IA emite NF-e, NFC-e, NFS-e, CT-e, MDF-e e DC-e.

Site - Documentação MCP - Demo ao vivo - Painel

English - Português

</div>

---

O que é

O Brasil NFe MCP é o primeiro servidor MCP (Model Context Protocol) que expõe a infraestrutura fiscal brasileira inteira como ferramentas, recursos e prompts pra qualquer cliente compatível com MCP - Claude Desktop, Cursor, Windsurf, VS Code Copilot, Zed, Continue.dev, JetBrains, ou sua própria aplicação.

Plugue o servidor no seu cliente MCP e o agente de IA passa a emitir nota fiscal por linguagem natural direto na conversa - "emite uma NFC-e de R$ 89,90 pro CPF tal" - e o documento vai pra SEFAZ. A IA descobre as tools sozinha, monta o payload pelo schema e traduz erros da SEFAZ pra linguagem clara.

REST API ou MCP?

Os dois são produtos de primeira linha da Brasil NFe e expõem a mesma infraestrutura fiscal - mesmo backend SEFAZ, mesmo SLA, mesmo suporte humano. A escolha é pelo tipo de integração, não pela qualidade:

| Use a API REST quando | Use o MCP quando | |---|---| | Você tem ERP, sistema de gestão ou app próprio com fluxo de emissão já definido | Quer um assistente IA, copilot ou agente decidindo quando e como emitir | | O processamento é em lote, agendado ou movido por evento de fila/webhook | O fluxo é conversacional - usuário (ou agente) no loop dirigindo cada passo | | A integração é determinística e você tem controle pixel-perfect da UI/UX | O cliente quer plugar Claude / Cursor / Copilot do contador direto na operação | | Volume alto, paralelismo otimizado, contratos de payload estáveis | Sessão interativa, exploratória, ad-hoc por linguagem natural |

Os dois conversam com o mesmo backend - dá pra ter o ERP integrado via REST e ao mesmo tempo plugar a IA do contador no MCP. Quando uma rota nova entra na API REST, ela já vira tool MCP automaticamente. Roadmap fiscal unificado, dois canais de consumo.

Endpoint público

https://api.brasilnfe.com.br/services/Mcp

| Recurso | Método | Caminho | |---|---|---| | JSON-RPC | POST | /services/Mcp | | SSE stream | GET | /services/Mcp | | Encerrar sessão | DELETE | /services/Mcp | | Discovery | GET | /.well-known/mcp | | Health | GET | /services/Mcp/info |

• Transport: Streamable HTTP
• Spec: MCP 2025-06-18
• Auth: Bearer token (Authorization: Bearer <TOKEN>)
• Rate-limit: 60 requisições/minuto por token (default)

O que está exposto

30+ tools em 8 categorias

| Categoria | Tools | O que faz | |---|---|---| | NF-e / NFC-e | nfe_emitir, nfe_emitir_complementar, nfe_previsualizar | Emite produto B2B (modelo 55) ou cupom de varejo (modelo 65), gera DANFE prévio | | NFS-e | nfse_emitir, nfse_consultar | Emite e consulta nota de serviço (5.500+ regras municipais embutidas) | | CT-e | cte_emitir, cte_desacordo | Emite conhecimento de transporte, registra desacordo do tomador | | MDF-e | mdfe_emitir, mdfe_encerrar | Emite manifesto de carga, encerra ao fim do transporte | | DC-e | dce_emitir | Emite declaração de conteúdo (PF/MEI) | | NF-EnerCom | nfenercom_gerar_arquivo, nfenercom_emitir | Emite NF de energia comercializada | | Eventos fiscais | evento_cancelar, evento_carta_correcao, evento_manifestar, evento_inutilizar | Cancela, corrige (CC-e), manifesta destinatário, inutiliza numeração | | Consultas SEFAZ | sefaz_status, cadastro_consultar, nota_listar, imposto_calcular | Status do serviço, IE, listagem de notas, simulador de impostos | | Cadastros | cliente_consultar/criar/editar, produto_consultar/criar/editar, tributacao_consultar/criar/editar | CRUD completo de clientes, produtos e regras tributárias (com fallback Receita Federal) | | Arquivos | arquivo_baixar, arquivo_baixar_evento, arquivo_baixar_periodo | Baixa XML/PDF individual ou ZIP do período | | Auxiliares | fci_gerar, health | Gera FCI (conteúdo importado), health-check |

5 resources (URI scheme brasilnfe://)

• brasilnfe://empresa/atual - snapshot da empresa logada
• brasilnfe://nfe/{chave}/xml - XML autorizado
• brasilnfe://nfe/{chave}/danfe - DANFE em PDF
• brasilnfe://evento/{chave}/{seq} - evento por sequencial
• brasilnfe://recebidas/{periodo} - notas recebidas no período

5 prompts prontos

• emitir_nfe_simples - fluxo guiado de emissão NF-e
• cancelar_nota - cancelamento com validação de prazo
• diagnostico_emissao - checagem completa antes de emitir
• relatorio_periodo - relatório fiscal do período
• carta_correcao - fluxo de CC-e com validação de campos permitidos

Quick start

1. Pegue seu token

Crie uma conta gratuita em brasilnfe.com.br e copie o token no painel. Modo homologação é grátis - você emite documentos de teste à vontade sem nada ir pra SEFAZ de produção.

2. Configure seu cliente MCP

Pega o arquivo correto em examples/ e cola na config do seu cliente:

• Claude Desktop
• Cursor
• Windsurf
• VS Code Copilot
• Zed
• cURL puro (JSON-RPC)

Substitua SEU_TOKEN_AQUI pelo token real e reinicie o cliente.

3. Fala com a IA

"Liste o status da SEFAZ pra SP."
"Consulte o CNPJ 39.658.743/0001-99."
"Emite uma NFC-e de R$ 89,90 pro consumidor com CPF 123.456.789-00."
"Cancela a chave 35..., justificativa: erro de digitação no valor."

Pronto. A IA descobre as tools sozinha, pede o que falta, valida, monta o payload, envia pra SEFAZ, e te entrega chave + protocolo + XML + PDF.

Demo sem cadastro

Abra brasilnfe.com.br/ai e converse com o assistente fiscal direto no navegador. Não envia pra SEFAZ de produção, mas mostra o fluxo completo com DANFE renderizado em tempo real ao lado do chat.

Boas práticas

• Sempre rode em homologação (tipoAmbiente: 2) antes de produção. Documento de teste tem CNPJ permitido e numeração separada - zero risco fiscal.
• Consulte cliente/produto/tributação antes de criar. As tools *_consultar evitam duplicatas e dão à IA o contexto pra reusar cadastros existentes.
• Confirme operações destrutivas. Cancelamento e inutilização são irreversíveis - a IA já é instruída a confirmar, mas verifique no seu fluxo.
• Feche sessões idle. DELETE /services/Mcp libera quota mais cedo.
• Auditoria sai automática. Todas as chamadas MCP ficam logadas no painel da sua empresa por 5 anos (LGPD-compliant).

Suporte

• Documentação: brasilnfe.com.br/mcp
• Demo ao vivo: brasilnfe.com.br/ai
• WhatsApp: +55 (31) 9 7168-5947 (horário comercial)
• E-mail: contato@brasilnfe.com.br (24/7)
• LGPD/DPO: dpo@brasilnfe.com.br

Sobre

Mantido pela Brasil NFe LTDA (CNPJ 39.658.743/0001-99), fundada em 2019 em Ipatinga/MG por Maxsuel Lima. Especialista em automação fiscal brasileira: 6 documentos fiscais cobertos, 5.500+ regras municipais NFS-e, 543 códigos SEFAZ embutidos, PCI DSS, e suporte humano 24/7.

Licença

MIT - você pode usar, modificar e distribuir livremente este repositório (configs, exemplos e docs). O servidor MCP em si é serviço operado pela Brasil NFe LTDA - veja Termos de Uso e Política de Privacidade.