mcp-nfe-br 0.6.2

MCP server for Brazilian electronic invoicing (NF-e / NFC-e)

mcp-nfe-br 🇧🇷

English | Portugues (Brasil)

---

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.6.1): 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. 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 and context-library/countries/br.md (in the source repo) for the full field-level reference.

---

Installation

Requirements

• Python ≥ 3.11
• mcp-einvoicing-core (installed automatically as a dependency)

Using uv (recommended)

uv add mcp-nfe-br

Using pip

pip install mcp-nfe-br

From source

git clone https://github.com/cmendezs/mcp-nfe-br.git
cd mcp-nfe-br
uv sync --all-extras

---

Configuration

Add the server to your MCP client configuration. For Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "nfe-br": {
      "command": "uvx",
      "args": ["mcp-nfe-br"]
    }
  }
}

For a local development installation:

{
  "mcpServers": {
    "nfe-br": {
      "command": "uv",
      "args": ["run", "mcp-nfe-br"],
      "cwd": "/path/to/mcp-nfe-br"
    }
  }
}

Environment variables

Variable	Description	Default
BR_READ_ONLY	Set to 1 to disable SEFAZ write tools (br__submit_nfe, br__distribute_dfe, br__submit_nfse, br__cancel_nfse). Safe mode for exploration. The SEFAZ environment (production/homologation) is selected per call via the tp_amb argument.	—
BR_CTE_READ_ONLY	Set to 1 to disable the CT-e write tools (br__submit_cte, br__cancel_cte, br__correct_cte). Kept distinct from BR_READ_ONLY so NF-e and CT-e can be gated independently.	—
LOG_LEVEL	Log level: DEBUG, INFO, WARNING, ERROR	INFO

---

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.

Parameter	Type	Required	Description
cpf	string	yes	CPF with or without ./- separators

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.

Parameter	Type	Required	Description
cnpj	string	yes	CNPJ with or without .///- separators

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. See context-library/countries/br.md for details.

---

br__generate_nfe

Generates an unsigned NF-e/NFC-e 4.00 document (<NFe><infNFe>…</infNFe></NFe>) from a BRInvoice object.

Parameter	Type	Required	Description
invoice	object	yes	BRInvoice document (modelo 55 or 65, groups ide/emit/dest/det/total/transp/pag)

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:

Tax	Supported codes	Behavior
ICMS	CST 00 (normal regime) or CSOSN 102 (Simples Nacional)	other codes raise DocumentGenerationError
PIS/COFINS	CST 01/02 (rate-based) or 04-09 (non-taxed)	group omitted if pis_cst/cofins_cst are None
IPI	CST 00/49/50/99 (taxed) or other (non-taxed)	group omitted if ipi_cst is None

[NEED: IBS/CBS/Imposto Seletivo — Grupo UB/W03 (NT 2025.002-RTC) not yet modeled, see context-library/countries/br.md "Known gaps"].

---

br__validate_nfe_xml

Validates an NF-e/NFC-e 4.00 XML document against the official PL_010d XSD (local "unsigned" variant, see note below).

Parameter	Type	Required	Description
xml_content	string	no*	XML as a string
xml_base64	string	no*	Base64-encoded XML

* 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.

Parameter	Type	Required	Description
c_uf	string	yes	IBGE state code (2 digits)
dh_emi	string	yes	Issue date/time (ISO 8601)
cnpj	string	yes	Issuer CNPJ (numeric or alphanumeric PL_010d)
modelo	string	yes	55 (NF-e) or 65 (NFC-e)
serie	string	yes	Document series
nnf	string	yes	Document number
tp_emis	string	no	Issuance type (default "1")
c_nf	string	no	Random numeric code (cNF, 8 digits); auto-generated if omitted

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) only, and no bundled/verified SEFAZ CT-e endpoint table — every SEFAZ call below requires an explicit endpoint_override.

br__generate_cte

Generates an unsigned CT-e 4.00 document (<CTe><infCte>…</infCte></CTe>) from a BRCTeDocument object.

Parameter	Type	Required	Description
cte	object	yes	BRCTeDocument (modelo 57, modal rodoviário, ICMS CST 00)

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).

Parameter	Type	Required	Description
xml_content	string	no*	XML as a string
xml_base64	string	no*	Base64-encoded XML

* 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

mcp-nfe-br/
├── src/
│   └── mcp_nfe_br/
│       ├── __init__.py
│       ├── server.py              # MCP entry point and tool registration
│       ├── models/
│       │   ├── __init__.py
│       │   └── invoice.py         # BRInvoice, BRInvoiceLine, NFeModelo, TipoOperacao
│       ├── standards/
│       │   ├── __init__.py
│       │   └── nfe_generator.py   # NFeGenerator — generates unsigned NF-e/NFC-e 4.00
│       ├── validators/
│       │   ├── __init__.py
│       │   └── nfe_xsd.py         # NFeXSDValidator — validates against PL_010d XSD (unsigned variant)
│       ├── schemas/nfe/           # Bundled XSDs (official + "_unsigned" variants)
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── validation.py      # br__validate_cpf, br__validate_cnpj
│       │   └── generation.py      # br__generate_nfe, br__validate_nfe_xml, br__build_access_key
│       └── utils/
│           ├── __init__.py
│           ├── document_ids.py    # validate_cpf, validate_cnpj
│           └── access_key.py      # build_access_key, access_key_check_digit
├── tests/
│   ├── conftest.py
│   ├── fixtures/
│   ├── test_tools/
│   │   ├── test_validation.py
│   │   └── test_generation.py
│   ├── test_standards/
│   │   └── test_nfe_generator.py
│   ├── test_validators/
│   │   └── test_nfe_xsd.py
│   └── test_utils/
│       └── test_access_key.py
├── specs/nfe/                     # Normative material (XSDs, MOC, Technical Notes, not published)
├── audit/
│   ├── audit_vs_core.py
│   └── report.json
├── .github/workflows/publish.yml
├── pyproject.toml
├── RELEASE.md
└── LICENSE

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)

---

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.

git clone https://github.com/cmendezs/mcp-nfe-br.git
cd mcp-nfe-br
uv sync --all-extras
uv run pytest
uv run ruff check src/mcp_nfe_br tests audit
uv run mypy src/mcp_nfe_br

---

Other e-invoicing MCP servers

Country	Server
🌍 Global	mcp-einvoicing-core
🇧🇪 Belgium	mcp-einvoicing-be
🇧🇷 Brazil	mcp-nfe-br
🇫🇷 France	mcp-facture-electronique-fr
🇩🇪 Germany	mcp-einvoicing-de
🇮🇹 Italy	mcp-fattura-elettronica-it
🇵🇱 Poland	mcp-ksef-pl
🇪🇸 Spain	mcp-facturacion-electronica-es

---

License

This project is licensed under Apache 2.0. See LICENSE for details.

---

Changelog

See RELEASE.md for the full version history.