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

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github/workflows		.github/workflows
audit		audit
specs		specs
src/mcp_nfe_br		src/mcp_nfe_br
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.pt-BR.md		README.pt-BR.md
RELEASE.md		RELEASE.md
pyproject.toml		pyproject.toml
server.json		server.json

Folders and files

Latest commit

History

Repository files navigation

mcp-nfe-br 🇧🇷

Introduction

Installation

Requirements

Using uv (recommended)

Using pip

From source

Configuration

Environment variables

Available tools

br__validate_cpf

br__validate_cnpj

br__generate_nfe

br__validate_nfe_xml

br__build_access_key

CT-e (modelo 57) tools

br__generate_cte

br__validate_cte_xml

br__consult_cte_sefaz_status

br__consult_cte

br__submit_cte

br__cancel_cte

br__correct_cte

Architecture

Relationship with mcp-einvoicing-core

Contributing

Other e-invoicing MCP servers

License

Changelog

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Using `uv` (recommended)

Using `pip`

`br__validate_cpf`

`br__validate_cnpj`

`br__generate_nfe`

`br__validate_nfe_xml`

`br__build_access_key`

`br__generate_cte`

`br__validate_cte_xml`

`br__consult_cte_sefaz_status`

`br__consult_cte`

`br__submit_cte`

`br__cancel_cte`

`br__correct_cte`

Relationship with `mcp-einvoicing-core`

Packages