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
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 logadabrasilnfe://nfe/{chave}/xml- XML autorizadobrasilnfe://nfe/{chave}/danfe- DANFE em PDFbrasilnfe://evento/{chave}/{seq}- evento por sequencialbrasilnfe://recebidas/{periodo}- notas recebidas no período
5 prompts prontos
emitir_nfe_simples- fluxo guiado de emissão NF-ecancelar_nota- cancelamento com validação de prazodiagnostico_emissao- checagem completa antes de emitirrelatorio_periodo- relatório fiscal do períodocarta_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:
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
*_consultarevitam 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/Mcplibera 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: [email protected] (24/7)
- LGPD/DPO: [email protected]
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.