mcp-nfe-br 🇧🇷

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

This server needs no credentials to run. The environment variables below are optional safety/logging toggles:

Environment variables

Variable	Description	Default
`BR_READ_ONLY`	Master switch. Set to `1` to disable write tools across all sub-formats: NF-e/NFC-e (`br__submit_nfe`, `br__distribute_dfe`), NFS-e (`br__submit_nfse`, `br__cancel_nfse`), and CT-e (`br__submit_cte`, `br__cancel_cte`, `br__correct_cte`). 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 only the CT-e write tools (`br__submit_cte`, `br__cancel_cte`, `br__correct_cte`), leaving NF-e/NFS-e writes enabled. Independent of `BR_READ_ONLY` — either variable set to `1` is sufficient to block CT-e writes; you do not need both.	—
`LOG_LEVEL`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`	`INFO`

Claude Desktop integration

To use this server with Claude, add this configuration to your claude_desktop_config.json file:

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

For a local development install:

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

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

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

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

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

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.

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, patched with the PL_010e_v.1.02 and PL_010f_v.1.04 deltas (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. 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.

`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
🇲🇽 Mexico	mcp-cfdi-mx
🇵🇱 Poland	mcp-ksef-pl
🇸🇬 Singapore	mcp-invoicenow-sg
🇪🇸 Spain	mcp-facturacion-electronica-es
🇦🇪 United Arab Emirates	mcp-einvoicing-ae

License

This project is licensed under Apache 2.0. See LICENSE for details. For the full version history, see CHANGELOG.md.

mcp-nfe-br 🇧🇷

Introduction

Installation

Requirements

Using uv (recommended)

Using pip

From source

Configuration

Environment variables

Claude Desktop integration

Cursor integration

Kiro integration

Available tools

br__validate_cpf

br__validate_cnpj

br__generate_nfe

br__validate_nfe_xml

br__build_access_key