MCP 服务器

brasilnfe-mcp

MCP server that exposes Brazilian tax infrastructure as tools, resources, and prompts, enabling AI agents to emit and manage fiscal documents (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e) through natural language.

README

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:

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.