{
  "markdown": "# mcp-nfe-br 🇧🇷\n\n[English](README.md) | [Portugues (Brasil)](README.pt-BR.md)\n\n<!-- mcp-name: io.github.cmendezs/mcp-nfe-br -->\n\n[![PyPI version](https://badge.fury.io/py/mcp-nfe-br.svg)](https://badge.fury.io/py/mcp-nfe-br)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-nfe-br.svg)](https://pypi.org/project/mcp-nfe-br/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n---\n\n## Introduction\n\n`mcp-nfe-br` is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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`](https://github.com/cmendezs/mcp-einvoicing-core), which provides the base data model, HTTP/OAuth2 utilities, and shared MCP server infrastructure.\n\n**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.\n\n## Installation\n\n### Requirements\n\n- Python ≥ 3.11\n- [`mcp-einvoicing-core`](https://github.com/cmendezs/mcp-einvoicing-core) (installed automatically as a dependency)\n\n### Using `uv` (recommended)\n\n```bash\nuv add mcp-nfe-br\n```\n\n### Using `pip`\n\n```bash\npip install mcp-nfe-br\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cmendezs/mcp-nfe-br.git\ncd mcp-nfe-br\nuv sync --all-extras\n```\n\n## Configuration\n\nThis server needs no credentials to run. The environment variables below are optional\nsafety/logging toggles:\n\n### Environment variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `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. | — |\n| `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. | — |\n| `LOG_LEVEL` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |\n\n## Claude Desktop integration\n\nTo use this server with Claude, add this configuration to your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"nfe-br\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-nfe-br\"]\n    }\n  }\n}\n```\n\nFor a local development install:\n\n```json\n{\n  \"mcpServers\": {\n    \"nfe-br\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"mcp-nfe-br\"],\n      \"cwd\": \"/path/to/mcp-nfe-br\"\n    }\n  }\n}\n```\n\n## Cursor integration\n\nCursor supports MCP servers via stdio. Add the configuration in:\n- **Global** (all projects): `~/.cursor/mcp.json`\n- **Project** (this repository only): `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"nfe-br\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-nfe-br\"]\n    }\n  }\n}\n```\n\nReload the Cursor window (`Ctrl+Shift+P` then *Reload Window*) to apply the changes.\n\n## Kiro integration\n\nKiro supports MCP servers via its dedicated configuration file. Two levels are available:\n- **Global** (all projects): `~/.kiro/settings/mcp.json`\n- **Workspace** (this repository only): `.kiro/settings/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"nfe-br\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-nfe-br\"],\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\nThe file is automatically reloaded on save. You can also open the config via the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) then *MCP*.\n\n## Available tools\n\n### `br__validate_cpf`\n\nValidates a CPF (Cadastro de Pessoas Físicas), the individual taxpayer identification number, using the Receita Federal modulo 11 algorithm.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `cpf` | `string` | yes | CPF with or without `.`/`-` separators |\n\nReturns a `TaxIdValidationResult` with `valid=True` and the cleaned value (11 digits) on success, or `valid=False` with an error message in Portuguese.\n\n---\n\n### `br__validate_cnpj`\n\nValidates 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.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `cnpj` | `string` | yes | CNPJ with or without `.`/`/`/`-` separators |\n\nReturns a `TaxIdValidationResult` with `valid=True` and the cleaned value (14 characters) on success, or `valid=False` with an error message in Portuguese.\n\n> ⚠️ **[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.\n\n---\n\n### `br__generate_nfe`\n\nGenerates an **unsigned** NF-e/NFC-e 4.00 document (`<NFe><infNFe>…</infNFe></NFe>`) from a `BRInvoice` object.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `invoice` | `object` | yes | `BRInvoice` document (modelo 55 or 65, groups `ide`/`emit`/`dest`/`det`/`total`/`transp`/`pag`) |\n\nReturns `{\"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.\n\nPhase 1 coverage for per-item tax groups:\n\n| Tax | Supported codes | Behavior |\n|---|---|---|\n| ICMS | CST `00` (normal regime) or CSOSN `102` (Simples Nacional) | other codes raise `DocumentGenerationError` |\n| PIS/COFINS | CST `01`/`02` (rate-based) or `04`-`09` (non-taxed) | group omitted if `pis_cst`/`cofins_cst` are `None` |\n| IPI | CST `00`/`49`/`50`/`99` (taxed) or other (non-taxed) | group omitted if `ipi_cst` is `None` |\n\n`[NEED: IBS/CBS/Imposto Seletivo — Grupo UB/W03 (NT 2025.002-RTC) not yet modeled, see context-library/countries/br.md \"Known gaps\"]`.\n\n---\n\n### `br__validate_nfe_xml`\n\nValidates 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).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml_content` | `string` | no* | XML as a string |\n| `xml_base64` | `string` | no* | Base64-encoded XML |\n\n\\* Exactly one of `xml_content`/`xml_base64` must be provided.\n\nReturns `{\"valid\": bool, \"errors\": [...], \"metadata\": {\"schema_version\": ...}}`.\n\n> **[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.\n\n---\n\n### `br__build_access_key`\n\nBuilds an access key (`chNFe`, 44 characters) with a modulo 11 check digit, from the components `cUF`, `dhEmi`, issuer CNPJ, model, series, and document number.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `c_uf` | `string` | yes | IBGE state code (2 digits) |\n| `dh_emi` | `string` | yes | Issue date/time (ISO 8601) |\n| `cnpj` | `string` | yes | Issuer CNPJ (numeric or alphanumeric PL_010d) |\n| `modelo` | `string` | yes | `55` (NF-e) or `65` (NFC-e) |\n| `serie` | `string` | yes | Document series |\n| `nnf` | `string` | yes | Document number |\n| `tp_emis` | `string` | no | Issuance type (default `\"1\"`) |\n| `c_nf` | `string` | no | Random numeric code (cNF, 8 digits); auto-generated if omitted |\n\nReturns `{\"chave_acesso\": ..., \"cnf\": ...}`.\n\n## CT-e (modelo 57) tools\n\nCT-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.\n\n### `br__generate_cte`\n\nGenerates an **unsigned** CT-e 4.00 document (`<CTe><infCte>…</infCte></CTe>`) from a `BRCTeDocument` object.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `cte` | `object` | yes | `BRCTeDocument` (modelo 57, modal rodoviário, ICMS CST 00) |\n\nReturns `{\"xml\": ..., \"chave_acesso\": ..., \"warnings\": [...]}`.\n\n### `br__validate_cte_xml`\n\nValidates 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).\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xml_content` | `string` | no* | XML as a string |\n| `xml_base64` | `string` | no* | Base64-encoded XML |\n\n\\* Exactly one of `xml_content`/`xml_base64` must be provided.\n\n### `br__consult_cte_sefaz_status`\n\nChecks SEFAZ CT-e webservice availability (`CTeStatusServicoV4`). Read-only, no confirmation required.\n\n### `br__consult_cte`\n\nQueries 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.\n\n### `br__submit_cte`\n\nSubmits 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`.\n\n### `br__cancel_cte`\n\nRequests cancellation of an authorized CT-e (event `110111`, `CTeRecepcaoEventoV4`). `cStat=135` indicates the cancellation was homologated. Gated.\n\n### `br__correct_cte`\n\nIssues 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.\n\nNot 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.\n\n## Architecture\n\n```\nmcp-nfe-br/\n├── src/\n│   └── mcp_nfe_br/\n│       ├── __init__.py\n│       ├── server.py              # MCP entry point and tool registration\n│       ├── models/\n│       │   ├── __init__.py\n│       │   └── invoice.py         # BRInvoice, BRInvoiceLine, NFeModelo, TipoOperacao\n│       ├── standards/\n│       │   ├── __init__.py\n│       │   └── nfe_generator.py   # NFeGenerator — generates unsigned NF-e/NFC-e 4.00\n│       ├── validators/\n│       │   ├── __init__.py\n│       │   └── nfe_xsd.py         # NFeXSDValidator — validates against PL_010d XSD (unsigned variant)\n│       ├── schemas/nfe/           # Bundled XSDs (official + \"_unsigned\" variants)\n│       ├── tools/\n│       │   ├── __init__.py\n│       │   ├── validation.py      # br__validate_cpf, br__validate_cnpj\n│       │   └── generation.py      # br__generate_nfe, br__validate_nfe_xml, br__build_access_key\n│       └── utils/\n│           ├── __init__.py\n│           ├── document_ids.py    # validate_cpf, validate_cnpj\n│           └── access_key.py      # build_access_key, access_key_check_digit\n├── tests/\n│   ├── conftest.py\n│   ├── fixtures/\n│   ├── test_tools/\n│   │   ├── test_validation.py\n│   │   └── test_generation.py\n│   ├── test_standards/\n│   │   └── test_nfe_generator.py\n│   ├── test_validators/\n│   │   └── test_nfe_xsd.py\n│   └── test_utils/\n│       └── test_access_key.py\n├── specs/nfe/                     # Normative material (XSDs, MOC, Technical Notes, not published)\n├── audit/\n│   ├── audit_vs_core.py\n│   └── report.json\n├── .github/workflows/publish.yml\n├── pyproject.toml\n├── RELEASE.md\n└── LICENSE\n```\n\n### Relationship with `mcp-einvoicing-core`\n\n`mcp-einvoicing-core` provides:\n- Base Pydantic models for invoices, parties, line items, and validation results (`InvoiceDocument`, `InvoiceLineItem`, `TaxIdValidationResult`)\n- Shared MCP server infrastructure (`EInvoicingMCPServer`)\n- HTTP/OAuth2 client, token cache, structured logging, exception hierarchy\n\n`mcp-nfe-br` adds Brazil-specific logic:\n- `BRInvoice` (extends `InvoiceDocument`, as NF-e/NFC-e has no EN 16931 lineage)\n- Group I fields (NCM, CFOP, ICMS/IPI/PIS/COFINS) in `BRInvoiceLine`\n- CPF/CNPJ validation (including the alphanumeric CNPJ from NT 2026.004)\n\n## Contributing\n\nContributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.\n\n```bash\ngit clone https://github.com/cmendezs/mcp-nfe-br.git\ncd mcp-nfe-br\nuv sync --all-extras\nuv run pytest\nuv run ruff check src/mcp_nfe_br tests audit\nuv run mypy src/mcp_nfe_br\n```\n\n## Other e-invoicing MCP servers\n\n| Country | Server |\n|---------|--------|\n| 🌍 Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |\n| 🇧🇪 Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |\n| 🇧🇷 Brazil | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |\n| 🇫🇷 France | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |\n| 🇩🇪 Germany | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |\n| 🇮🇳 India | [mcp-einvoicing-in](https://github.com/cmendezs/mcp-einvoicing-in) |\n| 🇮🇹 Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |\n| 🇲🇽 Mexico | [mcp-cfdi-mx](https://github.com/cmendezs/mcp-cfdi-mx) |\n| 🇵🇱 Poland | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |\n| 🇸🇬 Singapore | [mcp-invoicenow-sg](https://github.com/cmendezs/mcp-invoicenow-sg) |\n| 🇪🇸 Spain | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |\n| 🇦🇪 United Arab Emirates | [mcp-einvoicing-ae](https://github.com/cmendezs/mcp-einvoicing-ae) |\n\n## License\n\nThis project is licensed under **Apache 2.0**. See [LICENSE](LICENSE) for details. For the full version history, see [CHANGELOG.md](CHANGELOG.md).\n",
  "bytes": 15561,
  "sha": "02e09762554a4232bb8cedfbca014a87429fefee2805b792eecf502d18222809",
  "repo_slug": "cmendezs/mcp-nfe-br",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cmendezs_mcp_nfe_br_908ad163/readme"
}