mcp-nfe-br 🇧🇷
English | Portugues (Brasil)
[PyPI version]
[Python]
[License]
Introduction
mcp-nfe-br is an MCP (Model Context Protocol) server providing tools for issuing and validating Brazilian electronic fiscal documents: NF-e (modelo 55), NFC-e (modelo 65), NFS-e Nacional (ADN), and CT-e (modelo 57). This server is part of the mcp-einvoicing-* / mcp-*-* family, built on mcp-einvoicing-core, which provides the base data model, HTTP/OAuth2 utilities, and shared MCP server infrastructure.
Current status (v0.11.0): NF-e/NFC-e (modelo 55/65, schema 4.00) and NFS-e Nacional (ADN, schema v1.01) generation, ICP-Brasil signing, XSD validation, and gated SEFAZ/ADN submission are implemented. NF-e/NFC-e now also covers the 010e_v.1.02 schema delta (DANFE Simplificado Tipo 2 — tpImp=6, cIndOp, ISUFEmit, and the SEFAZ alert-message response group) and the 010f_v.1.04 delta (NT 2026.007 — emit/IE optional for taxpayers exclusively subject to IBS/CBS, produção 2026-11-03) on top of the PL_010d base. CT-e (modelo 57) generation/signing/validation and SEFAZ event submission (cancelamento, Carta de Correção) were added starting v0.6.0 — v1 scope is intentionally narrow: modal rodoviário only, ICMS CST 00 only, and no bundled/verified CT-e webservice endpoint table (every SEFAZ CT-e call requires an explicit endpoint_override). See the "CT-e (modelo 57)" tools section below for the full field-level reference. Since v0.11.0, NF-e/NFC-e also supports vUnComLiq/vProdLiq/vProdLiqTot, emit/tpRegimeIBSCBS, cAtivSN, gTribSN and gPgtoVinc (NT 2026.005, 2026.006 and 2026.008); the IBS/CBS group emission is known not to validate against the official schema yet.
Installation
Requirements
Using uv (recommended)
Using pip
From source
Configuration
This server needs no credentials to run. The environment variables below are optional
safety/logging toggles:
Environment variables
Claude Desktop integration
To use this server with Claude, add this configuration to your claude_desktop_config.json file:
For a local development install:
Cursor integration
Cursor supports MCP servers via stdio. Add the configuration in:
- Global (all projects):
~/.cursor/mcp.json
- Project (this repository only):
.cursor/mcp.json
Reload the Cursor window (Ctrl+Shift+P then Reload Window) to apply the changes.
Kiro integration
Kiro supports MCP servers via its dedicated configuration file. Two levels are available:
- Global (all projects):
~/.kiro/settings/mcp.json
- Workspace (this repository only):
.kiro/settings/mcp.json
The file is automatically reloaded on save. You can also open the config via the command palette (Cmd+Shift+P / Ctrl+Shift+P) then MCP.
Available tools
br__validate_cpf
Validates a CPF (Cadastro de Pessoas Físicas), the individual taxpayer identification number, using the Receita Federal modulo 11 algorithm.
Returns a TaxIdValidationResult with valid=True and the cleaned value (11 digits) on success, or valid=False with an error message in Portuguese.
br__validate_cnpj
Validates a CNPJ (Cadastro Nacional da Pessoa Jurídica), the business taxpayer identification number. Accepts both the traditional numeric format (14 digits) and the alphanumeric format introduced by NT 2026.004 (PL_010d), effective in homologation from 2026-06-01 and in production from 2026-07-01.
Returns a TaxIdValidationResult with valid=True and the cleaned value (14 characters) on success, or valid=False with an error message in Portuguese.
⚠️ [Unverified]: the check-digit algorithm for the alphanumeric CNPJ format was implemented based on secondary sources, as the primary source ("NT Conjunta DFe 2025.001") is not yet available locally.
br__generate_nfe
Generates an unsigned NF-e/NFC-e 4.00 document (<NFe><infNFe>…</infNFe></NFe>) from a BRInvoice object.
Returns {"xml": ..., "chave_acesso": ..., "warnings": [...]}. The warnings in Portuguese remind that the document is not signed (ICP-Brasil) and was not transmitted to SEFAZ. Both steps are the responsibility of a separate process.
Phase 1 coverage for per-item tax groups:
IBS/CBS (item IBSCBS including gTribSN, and the monofásico group gIBSCBSMono), Imposto Seletivo and the totals groups (ISTot, IBSCBSTot) are modeled and XSD-validated against PL_010h_v1.03. Emitters without emit/IE (contribuinte exclusivo do IBS/CBS, NT 2026.007) are supported and authorized on SVRS. Diferimento, devolução, redução and Suframa subgroups are not yet modeled.
br__validate_nfe_xml
Validates an NF-e/NFC-e 4.00 XML document against the official PL_010d XSD, patched with the PL_010e_v.1.02 and PL_010f_v.1.04 deltas (local "unsigned" variant, see note below).
* Exactly one of xml_content/xml_base64 must be provided.
Returns {"valid": bool, "errors": [...], "metadata": {"schema_version": ...}}.
[Inference]: the official XSD (nfe_v4.00.xsd/leiauteNFe_v4.00.xsd, PL_010d) requires <ds:Signature> as a mandatory child of <NFe>. Since Phase 1 generates unsigned documents, this tool validates against a local derived copy (nfe_v4.00_unsigned.xsd) where <ds:Signature> has been made optional (minOccurs="0"). Validation of signed documents (future phase) should use the official XSD without modifications.
br__build_access_key
Builds an access key (chNFe, 44 characters) with a modulo 11 check digit, from the components cUF, dhEmi, issuer CNPJ, model, series, and document number.
Returns {"chave_acesso": ..., "cnf": ...}.
CT-e (modelo 57) tools
CT-e (Conhecimento de Transporte Eletrônico) coverage started at v0.6.0. v1 scope is intentionally narrow: modal rodoviário only (other modais raise an error), ICMS CST 00 (tributação normal) and 40/41/51 (ICMS45) only, and no bundled/verified SEFAZ CT-e endpoint table — every SEFAZ call below requires an explicit endpoint_override. Since v0.7.0, br__generate_cte also accepts the Reforma Tributária do Consumo (IBS/CBS) fields introduced by NT 2026.002 — imp/IBSCBS, emit/ISUFEmit, and ide/tpPagAnt+gPagAntecipado — with the NT's self-contained business rules enforced at the model layer; rules that require a live SEFAZ database lookup are not checked. Since v0.10.0 it also supports vPrest/vTPrestLiq, imp/vTotDFe, emit/tpRegimeIBSCBS, and imp/IBSCBS/gTribSN (NT 2026.004 v1.01 and NT 2026.005 v1.00); ide/gMultaJuros (NT 2026.004, with the stateless rules RV 1072, 1073 and 1078) and pgtoVinc (NT 2026.001) are supported since v0.13.0; the ICMS advance-payment group is not yet.
br__generate_cte
Generates an unsigned CT-e 4.00 document (<CTe><infCte>…</infCte></CTe>) from a BRCTeDocument object.
Returns {"xml": ..., "chave_acesso": ..., "warnings": [...]}.
br__validate_cte_xml
Validates a CT-e 4.00 XML document against the bundled PL_CTe_400 XSD (auto-selects the unsigned or official signed schema based on <ds:Signature> presence).
* Exactly one of xml_content/xml_base64 must be provided.
br__consult_cte_sefaz_status
Checks SEFAZ CT-e webservice availability (CTeStatusServicoV4). Read-only, no confirmation required.
br__consult_cte
Queries a CT-e's status by access key (CTeConsultaV4). Read-only, no confirmation required — it queries one already-known document, not a bulk data pull.
br__submit_cte
Submits a signed CT-e to SEFAZ authorization (CTeRecepcaoSincV4, synchronous). The payload is automatically GZip-compressed and Base64-encoded before transmission, per the CT-e MOC. Gated with a two-step confirmation (ConfirmationGate) and BR_CTE_READ_ONLY.
br__cancel_cte
Requests cancellation of an authorized CT-e (event 110111, CTeRecepcaoEventoV4). cStat=135 indicates the cancellation was homologated. Gated.
br__correct_cte
Issues a Carta de Correção Eletrônica (event 110110, CTeRecepcaoEventoV4). Per Art. 58-B of CONVÊNIO/SINIEF 06/89, a CC-e cannot alter tax values, party registration data, or the issue/departure date. Gated.
Not yet implemented: br__distribute_cte_dfe (CTeDistribuicaoDFe) — the bundled specification confirms the request payload shape but not the webservice's method name, WSDL namespace, or message-wrapper element.
Architecture
Relationship with mcp-einvoicing-core
mcp-einvoicing-core provides:
- Base Pydantic models for invoices, parties, line items, and validation results (
InvoiceDocument, InvoiceLineItem, TaxIdValidationResult)
- Shared MCP server infrastructure (
EInvoicingMCPServer)
- HTTP/OAuth2 client, token cache, structured logging, exception hierarchy
mcp-nfe-br adds Brazil-specific logic:
BRInvoice (extends InvoiceDocument, as NF-e/NFC-e has no EN 16931 lineage)
- Group I fields (NCM, CFOP, ICMS/IPI/PIS/COFINS) in
BRInvoiceLine
- CPF/CNPJ validation (including the alphanumeric CNPJ from NT 2026.004)
Vendor neutrality
This server implements the standard itself: it builds, validates, and signs the document
locally. It is not a client for a commercial invoicing platform, and your signing keys and
credentials never leave your own infrastructure.
Invoices go directly to SEFAZ (NF-e/NFC-e) and the CT-e SEFAZ endpoint with your own digital
certificate; no intermediary is involved.
Contributing
Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.
Other e-invoicing MCP servers
License
This project is licensed under Apache 2.0. See LICENSE for details. For the full version history, see CHANGELOG.md.