About fiscal
Brasil NFe MCP exposes Brazilian fiscal infrastructure as tools, resources, and prompts for businesses and finance teams handling tax documents through conversation. It covers multiple electronic document types, SEFAZ queries, fiscal events, and file downloads, using the same backend as Brasil NFe's REST API.
Key features
- 01Issue and query six Brazilian fiscal document types
- 02Handle cancellation, corrections, and recipient events
- 03Check SEFAZ, taxpayer registrations, and taxes
- 04Manage customers, products, and tax rules
- 05Download XML, PDF, and period archives
Use cases
- 01Issue an NF-e or NFC-e through conversation
- 02Check SEFAZ status and company registration details
- 03Cancel a document or submit a correction event
- 04Download a single invoice or files for a period
MCP support
The MCP service uses Streamable HTTP to provide compatible clients with more than 30 tools, five resources, and five prompts, with Bearer token authentication. It shares its fiscal backend with the Brasil NFe REST API.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
Endpoint
https://api.brasilnfe.com.br/services/McpCopy install command
Claude CodeTerminal
claude mcp add --transport http br-com-brasilnfe-fiscal https://api.brasilnfe.com.br/services/McpCursor.cursor/mcp.json
{"mcpServers":{"br-com-brasilnfe-fiscal":{"type":"http","url":"https://api.brasilnfe.com.br/services/Mcp"}}}Open in CursorVS Code.vscode/mcp.json
{"servers":{"br-com-brasilnfe-fiscal":{"type":"http","url":"https://api.brasilnfe.com.br/services/Mcp"}}}Open in VS CodeClaude Desktopclaude_desktop_config.json
{"mcpServers":{"br-com-brasilnfe-fiscal":{"type":"http","url":"https://api.brasilnfe.com.br/services/Mcp"}}}Windsurf~/.codeium/windsurf/mcp_config.json
{"mcpServers":{"br-com-brasilnfe-fiscal":{"serverUrl":"https://api.brasilnfe.com.br/services/Mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
All endpoints
Streamable HTTP
https://api.brasilnfe.com.br/services/McpAuth requiredTools
34| Parameter | Type | Required | Description |
|---|---|---|---|
| Lote | integer|null | No | Invoice batch |
| Serie | integer|null | No | Série da nota Fiscal |
| Codigo | string|null | No | B03 - Código numérico que compõe a Chave de Acesso. Número aleatório gerado pelo emitente para cada NF-e. |
| Numero | integer|null | No | Número da nota fiscal |
| Cliente | object|null | No | Destinatário da nota. OBRIGATÓRIO para NF-e (modelo 55). Para NFC-e (modelo 65) só é obrigatório quando IndicadorPresenca = 4 (entrega a domicílio). Quando informado para NF-e mod 55, exige: CpfCnpj, NmCliente, IndicadorIe (1/2/9), Endereco com Logradouro e UF (e CEP/Município/Bairro quando não exportação). |
| Cliente.Ie | string|null | No | |
| Cliente.IsUf | string|null | No | |
| Cliente.Contato | object|null | No | |
| Cliente.Contato.Fax | string|null | No | |
| Cliente.Contato.Email | string|null | No | |
| Cliente.Contato.Telefone | string|null | No | |
| Cliente.CpfCnpj | string | Yes | CPF (11 dígitos) ou CNPJ (14 dígitos) do destinatário. Aceita com ou sem máscara - o sistema normaliza. Obrigatório para NF-e (modelo 55). Em operações de exportação (CFOP iniciado em 3/7) pode ter de 5 a 20 caracteres. |
| Cliente.Endereco | object|null | No | |
| Cliente.Endereco.Uf | string|null | No | |
| Cliente.Endereco.Cep | string|null | No | |
| Cliente.Endereco.Pais | string|null | No | |
| Cliente.Endereco.Bairro | string|null | No | |
| Cliente.Endereco.Numero | string|null | No | |
| Cliente.Endereco.CodPais | integer | No | |
| Cliente.Endereco.Municipio | string|null | No | |
| Cliente.Endereco.Logradouro | string|null | No | |
| Cliente.Endereco.Complemento | string|null | No | |
| Cliente.Endereco.CodMunicipio | string|null | No | |
| Cliente.NmCliente | string | Yes | Nome/Razão Social do destinatário (máx 60 caracteres). Obrigatório para NF-e (modelo 55). |
| Cliente.IndicadorIe | enum | No | Indicador de Inscrição Estadual. Para NFC-e (modelo 65) DEVE ser 9. Para NF-e (modelo 55) aceita 1, 2 ou 9. Valores: 1 - Contribuinte ICMS (informar a IE do destinatário); 2 - Contribuinte isento de Inscrição no cadastro de Contribuintes do ICMS; 9 - Não Contribuinte, que pode ou não possuir Inscrição Estadual no Cadastro de Contribuintes do ICMS1 | 2 | 9 |
| Entrega | object|null | No | |
| Entrega.Ie | string|null | No | |
| Entrega.Nome | string|null | No | |
| Entrega.Contato | object|null | No | |
| Entrega.Contato.Fax | string|null | No | |
| Entrega.Contato.Email | string|null | No | |
| Entrega.Contato.Telefone | string|null | No | |
| Entrega.CpfCnpj | string|null | No | |
| Entrega.Endereco | object|null | No | |
| Entrega.Endereco.Uf | string|null | No | |
| Entrega.Endereco.Cep | string|null | No | |
| Entrega.Endereco.Pais | string|null | No | |
| Entrega.Endereco.Bairro | string|null | No | |
| Entrega.Endereco.Numero | string|null | No | |
| Entrega.Endereco.CodPais | integer | No | |
| Entrega.Endereco.Municipio | string|null | No | |
| Entrega.Endereco.Logradouro | string|null | No | |
| Entrega.Endereco.Complemento | string|null | No | |
| Entrega.Endereco.CodMunicipio | string|null | No | |
| Exporta | object|null | No | |
| Exporta.UFSaidaPais | string|null | No | Sigla da UF de Embarque ou de transposição de fronteira |
| Exporta.LocalDespacho | string|null | No | Descrição do local de despacho |
| Exporta.LocalEmbarqueTransp | string|null | No | Descrição do Local de Embarque ou de transposição de fronteira |
| Cobranca | object|null | No | |
| Cobranca.Fatura | object|null | No | |
| Cobranca.Fatura.Valor | number | No | |
| Cobranca.Fatura.Numero | string|null | No | |
| Cobranca.Fatura.Desconto | number | No | |
| Cobranca.Fatura.ValorLiquido | number | No | |
| Cobranca.Parcelas | array|null | No | |
| Produtos | array | Yes | Itens da nota fiscal. Mínimo 1 item. |
| Retencoes | object|null | No | Retenções federais totais da nota (IRRF, PIS/COFINS/CSLL retidos, Previdência). Gera a tag retTrib no XML. |
| Retencoes.ValorIRRF | number|null | No | Valor retido do IRRF |
| Retencoes.ValorRetidoPIS | number|null | No | Valor retido de PIS |
| Retencoes.BaseCalculoIRRF | number|null | No | Base de cálculo do IRRF |
| Retencoes.ValorRetidoCSLL | number|null | No | Valor retido de CSLL |
| Retencoes.ValorRetidoCOFINS | number|null | No | Valor retido de COFINS |
| Retencoes.ValorRetencaoPrevidencia | number|null | No | Valor da retenção da Previdência Social |
| Retencoes.BaseCalculoRetencaoPrevidencia | number|null | No | Base de cálculo da retenção da Previdência Social |
| TipoDanfe | enum | No | Formato de impressão do DANFE (tag tpImp da NF-e). Não informado = padrão atual (1-Retrato para NF-e, 4 para NFC-e). Valores: 0 - Sem geração de DANFE; 1 - DANFE normal, Retrato (padrão NF-e); 2 - DANFE normal, Paisagem; 3 - DANFE Simplificado; 4 - DANFE NFC-e (padrão NFC-e; somente modelo 65); 5 - DANFE NFC-e em mensagem eletrônica (somente modelo 65); 6 - DANFE Simplificado Tipo 2 (NT 2026.002/2026.003, Ajuste SINIEF 13/26; somente modelo 55) - NF-e de varejo em operação típica de NFC-e, impressa em bobina com QR Code. Exige operação interna (CFOP 5xxx), consumidor final, finalidade 1-Normal, saída, sem notas referenciadas e IndicadorPresenca 1, 4 ou 5.0 | 1 | 2 | 3 | 4 | 5 | 6 | null |
| Finalidade | enum | Yes | Purpose of issuing the invoice. Values: 1 - Normal (most common case); 2 - Complementary (referencing a previous invoice in NFReferencia); 3 - Adjustment; 4 - Return; 5 - Credit note; 6 - Debit note1 | 2 | 3 | 4 | 5 | 6 |
| Observacao | string|null | No | |
| Pagamentos | array|null | No | Payment methods. REQUIRED when Finalidade = 1 (Normal). May be empty for purposes 2/3/4/5/6. For NFC-e (mod 65), there must be at least one payment with FormaPagamento different from "90" (no payment). |
| TpNFDebito | enum | No | Debit note type. Required when Finalidade = 6. SEFAZ code: Values: 1 - Transfer of credits to Cooperatives; 2 - Credit reversal for immune/exempt sales; 3 - Debits from invoices not processed in the assessment; 4 - Fines and interest; 5 - Transfer of credit through succession; 6 - Advance payment; 7 - Inventory loss1 | 2 | 3 | 4 | 5 | 6 | 7 | null |
| Transporte | object|null | No | |
| Transporte.IE | string|null | No | |
| Transporte.UF | string|null | No | |
| Transporte.CNPJ | string|null | No | |
| Transporte.Balsa | string|null | No | |
| Transporte.Vagao | string|null | No | |
| Transporte.Reboque | array|null | No | |
| Transporte.Veiculo | object|null | No | |
| Transporte.Veiculo.UF | string|null | No | |
| Transporte.Veiculo.RNTC | string|null | No | |
| Transporte.Veiculo.Placa | string|null | No | |
| Transporte.Volumes | array|null | No | |
| Transporte.DsEndereco | string|null | No | |
| Transporte.NmMunicipio | string|null | No | |
| Transporte.ModalidadeFrete | enum | No | 0 - Freight contracted by the Sender (CIF); 1 - Freight contracted by the Recipient (FOB); 2 - Freight contracted by Third Parties; 3 - Sender's own transport; 4 - Recipient's own transport; 9 - No transport occurrence0 | 1 | 2 | 3 | 4 | 9 |
| Transporte.NmTransportador | string|null | No | |
| ValorFrete | number|null | No | Total freight amount for the invoice. When provided, it is distributed proportionally among items (in proportion to each item's ValorTotal), REPLACING the ValorFrete provided for each product. Not provided (null) = the freight for each item is used as submitted. |
| ValorTotal | number|null | No | Expected invoice total (vNF), used only for validation. If provided and different from the calculated total (products - discounts + freight + insurance + other expenses + taxes included in the total), issuance is blocked and the error details the calculation. Not provided (null) = no validation. |
| DataEmissao | string|null | No | Date and time of the product/service's outbound or inbound movement (sends the current date if not provided) |
| EnviarEmail | boolean | No | |
| TpNFCredito | enum | No | Credit note type. Required when Finalidade = 5. SEFAZ code: Values: 1 - Fines and interest; 2 - Appropriation of presumed IBS credit on the debit balance in the ZFM; 3 - Return due to total refusal at delivery or inability to locate the recipient; 4 - Reduction of amounts; 5 - Transfer of credit through succession; 6 - Return due to partial refusal at delivery1 | 2 | 3 | 4 | 5 | 6 | null |
| CalcularIBPT | boolean | No | Calculates the approximate tax amount (vTotTrib, IBPT table, Lei 12.741/2012). Default: true. |
| NFReferencia | array|null | No | Reference invoices |
| TipoAmbiente | enum | Yes | SEFAZ environment identification. Values: 1 - Production (REAL issuance, with fiscal value, irreversible); 2 - Homologation (test, without fiscal value - use during development and testing)1 | 2 |
| Intermediador | object|null | No | Intermediary/marketplace data (third-party website or platform). |
| Intermediador.Cnpj | string | Yes | CNPJ of the transaction intermediary (marketplace/third-party platform). Required. |
| Intermediador.IdCadIntTran | string | Yes | Seller identification on the intermediary's website (registered user/login). Required. |
| Justificativa | string|null | No | Use when the issuance type is not normal |
| ValorDesconto | number|null | No | Total discount amount for the invoice. When provided, it is distributed proportionally among items (in proportion to each item's ValorTotal), REPLACING the ValorDesconto provided for each product. Not provided (null) = the discount for each item is used as submitted. |
| ConsumidorFinal | boolean | No | Indicates whether the transaction is with a final consumer (for NFC-e, must be 1; validate!) |
| ModeloDocumento | enum | Yes | Fiscal document model code. Values: 55 - NF-e (B2B / recipient identified by CPF/CNPJ); 65 - NFC-e (final consumer / retail)55 | 65 |
| ObservacaoFisco | string|null | No | |
| DataEntradaSaida | string|null | No | Date and time of the product/service's outbound or inbound movement |
| NaturezaOperacao | string | Yes | Description of the nature of the transaction (max. 60 characters). Examples: "Venda de mercadoria", "Remessa para industrialização", "Devolução de venda". |
| IndicadorPresenca | enum | Yes | Indicador de presença do comprador no estabelecimento comercial no momento da operação. Padrão sugerido para NF-e B2B = 9 (operação não presencial, outros). Para NFC-e varejo = 1 (presencial). Valores: 0 - Não se aplica; 1 - Operação presencial;; 2 - Operação não presencial, pela Internet;; 3 - Operação não presencial, Teleatendimento;; 4 - NFC-e em operação com entrega a domicílio;; 5 - Presencial fora do estabelecimento;; 9 - Operação não presencial, outros.0 | 1 | 2 | 3 | 4 | 5 | 9 |
| confirmacaoUsuario | boolean | No | Envie true SOMENTE depois que o usuário viu a pré-visualização final e confirmou explicitamente a emissão nesta conversa. Obrigatório em conexões OAuth. |
| IdentificadorInterno | string|null | No | |
| NFPagamentoAntecipado | array|null | No | Grupo de notas de antecipação de pagamento (gPagAntecipado - Reforma Tributária). |
Details
From the project 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
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.
Comments
Markdown supported
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.