mcp-nfe-br

Name: mcp-nfe-br
Author: cmendezs

本地服务

github.com/cmendezs金融数据07 周前更新

代码仓库

关于 mcp-nfe-br

mcp-nfe-br 是面向巴西电子税务单据处理的 MCP 服务，适用于需要生成、验证及提交税务 XML 的系统。它覆盖 NF-e、NFC-e、NFS-e Nacional 和范围受限的 CT-e，并在本地构建与验证文档。

主要功能

01生成 NF-e、NFC-e 与 NFS-e 文档
02生成和验证 CT-e XML
03按 XSD 验证税务单据
04验证 CPF 与 CNPJ
05查询及提交 SEFAZ 单据

适用场景

01生成巴西电子发票 XML
02检查单据是否符合 XSD
03验证纳税人识别号
04查询或提交 CT-e 至 SEFAZ

MCP 相关

作为 MCP 服务，它向 MCP 客户端提供巴西税务单据生成、验证、身份号校验及 SEFAZ 查询和提交工具。提交和更正等写入操作可通过只读开关限制。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cmendezs-mcp-nfe-br": {
      "command": "uvx",
      "args": [
        "mcp-nfe-br"
      ],
      "env": {
        "BR_READ_ONLY": "<BR_READ_ONLY>",
        "BR_CTE_READ_ONLY": "<BR_CTE_READ_ONLY>",
        "LOG_LEVEL": "<LOG_LEVEL>"
      }
    }
  }
}

启动命令uvx mcp-nfe-br

需要配置的环境变量

BR_READ_ONLYMaster switch. Set to '1' to disable all write-side tools across NF-e, NFC-e, NFS-e, AND CT-e (br__submit_nfe, br__distribute_dfe, br__submit_nfse, br__cancel_nfse, br__submit_cte, br__cancel_cte, br__correct_cte). Read-only mode for safe exploration. Setting only this variable is sufficient to disable all CT-e writes too — BR_CTE_READ_ONLY is an additional, independent gate, not a required second step.

BR_CTE_READ_ONLYSet to '1' to disable the three CT-e write-side tools (br__submit_cte, br__cancel_cte, br__correct_cte). Independent of BR_READ_ONLY — either variable being set to '1' is sufficient to block CT-e writes; use this one to gate CT-e alone while leaving NF-e/NFS-e writes enabled.

LOG_LEVELLogging level: DEBUG, INFO (default), WARNING, or ERROR

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypimcp-nfe-br0.9.1stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
cnpj	string	是	CNPJ 字符串，可包含或不包含 ``.``/``/``/``-`` 分隔符。

详细介绍

mcp-nfe-br 🇧🇷

English | Portugues (Brasil)

简介

mcp-nfe-br 是一个 MCP（Model Context Protocol）服务，提供用于签发和验证巴西电子税务单据的工具：NF-e（modelo 55）、NFC-e（modelo 65）、NFS-e Nacional（ADN）和 CT-e（modelo 57）。此服务属于 mcp-einvoicing-* / mcp-*-* 系列，基于 mcp-einvoicing-core 构建，后者提供基础数据模型、HTTP/OAuth2 工具集和共享的 MCP 服务基础架构。

当前状态（v0.6.5）： 已实现 NF-e/NFC-e（modelo 55/65，schema 4.00）和 NFS-e Nacional（ADN，schema v1.01）的生成、ICP-Brasil 签名、XSD 验证，以及受控的 SEFAZ/ADN 提交。NF-e/NFC-e 还涵盖了 010e_v.1.02 schema 差异（DANFE Simplificado Tipo 2 — tpImp=6、cIndOp、ISUFEmit 和 SEFAZ 警告消息响应组），以及在 PL_010d 基础上新增的 010f_v.1.04 差异（NT 2026.007 — 对仅适用 IBS/CBS 的纳税人，emit/IE 为可选，produção 2026-11-03）。从 v0.6.0 起，新增了 CT-e（modelo 57） 的生成、签名和验证，以及 SEFAZ 事件提交（取消、Carta de Correção）——v1 的范围刻意设得较窄：仅限 modal rodoviário、仅限 ICMS CST 00，且不附带／不验证 CT-e Web 服务端点表（每次 SEFAZ CT-e 调用都必须显式提供 endpoint_override）。完整的字段级参考信息请参阅下文的“CT-e（modelo 57）”工具章节。

安装

要求

Python ≥ 3.11
mcp-einvoicing-core（作为依赖项自动安装）

使用 `uv`（推荐）

uv add mcp-nfe-br

使用 `pip`

pip install mcp-nfe-br

从源码安装

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

配置

运行此服务无需凭据。以下环境变量为可选的安全／日志开关：

环境变量

变量	描述	默认值
`BR_READ_ONLY`	总开关。设为 `1` 可禁用所有子格式的写入工具：NF-e/NFC-e（`br__submit_nfe`、`br__distribute_dfe`）、NFS-e（`br__submit_nfse`、`br__cancel_nfse`）和 CT-e（`br__submit_cte`、`br__cancel_cte`、`br__correct_cte`）。适用于安全探索模式。SEFAZ 环境（生产／同源测试）通过每次调用的 `tp_amb` 参数选择。	—
`BR_CTE_READ_ONLY`	设为 `1` 可仅禁用 CT-e 写入工具（`br__submit_cte`、`br__cancel_cte`、`br__correct_cte`），同时保持 NF-e/NFS-e 写入功能启用。此变量独立于 `BR_READ_ONLY`——任一变量设为 `1` 就足以阻止 CT-e 写入；无需同时设置两个变量。	—
`LOG_LEVEL`	日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR`	`INFO`

Claude Desktop 集成

要在 Claude 中使用此服务，请将以下配置添加到 claude_desktop_config.json 文件：

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

对于本地开发安装：

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

Cursor 集成

Cursor 通过 stdio 支持 MCP 服务。请在以下位置添加配置：

全局（所有项目）：~/.cursor/mcp.json
项目级（仅此仓库）：.cursor/mcp.json

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

重新加载 Cursor 窗口（按 Ctrl+Shift+P，然后选择 Reload Window）以应用更改。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务。提供两个配置级别：

全局（所有项目）：~/.kiro/settings/mcp.json
工作区（仅此仓库）：.kiro/settings/mcp.json

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

保存后文件会自动重新加载。你也可以通过命令面板打开配置（按 Cmd+Shift+P / Ctrl+Shift+P），然后选择 MCP。

可用工具

`br__validate_cpf`

使用 Receita Federal 的 modulo 11 算法验证 CPF（Cadastro de Pessoas Físicas，个人纳税人识别号）。

参数	类型	必填	说明
`cpf`	`string`	是	带或不带 `.`/`-` 分隔符的 CPF

成功时返回 TaxIdValidationResult，其中 valid=True，并包含清理后的值（11 位数字）；失败时返回 valid=False，并附带葡萄牙语错误消息。

`br__validate_cnpj`

验证 CNPJ（Cadastro Nacional da Pessoa Jurídica，企业纳税人识别号）。支持传统的数字格式（14 位数字）以及 NT 2026.004（PL_010d）引入的字母数字格式，该格式将于 2026-06-01 起在 homologation 环境生效，并于 2026-07-01 起在生产环境生效。

参数	类型	必填	说明
`cnpj`	`string`	是	带或不带 `.`/`/`/`-` 分隔符的 CNPJ

成功时返回 TaxIdValidationResult，其中 valid=True，并包含清理后的值（14 个字符）；失败时返回 valid=False，并附带葡萄牙语错误消息。

⚠️ [Unverified]：字母数字格式 CNPJ 的校验位算法基于二手资料实现，因为主要来源（“NT Conjunta DFe 2025.001”）目前尚未在本地提供。

`br__generate_nfe`

根据 BRInvoice 对象生成未签名的 NF-e/NFC-e 4.00 文档（<NFe><infNFe>…</infNFe></NFe>）。

参数	类型	必填	说明
`invoice`	`object`	是	`BRInvoice` 文档（modelo 55 或 65，包含 `ide`/`emit`/`dest`/`det`/`total`/`transp`/`pag` 组）

返回 {"xml": ..., "chave_acesso": ..., "warnings": [...]}。葡萄牙语警告会提醒：该文档未签名（ICP-Brasil），且未传输至 SEFAZ。这两个步骤由单独的流程负责。

第一阶段支持的逐项税务组：

税种	支持的代码	行为
ICMS	CST `00`（正常税制）或 CSOSN `102`（Simples Nacional）	其他代码会引发 `DocumentGenerationError`
PIS/COFINS	CST `01`/`02`（按税率计税）或 `04`-`09`（免税）	若 `pis_cst`/`cofins_cst` 为 `None`，则省略该组
IPI	CST `00`/`49`/`50`/`99`（计税）或其他代码（不计税）	若 `ipi_cst` 为 `None`，则省略该组

[NEED: IBS/CBS/Imposto Seletivo — Grupo UB/W03 (NT 2025.002-RTC) not yet modeled]。

`br__validate_nfe_xml`

根据官方 PL_010d XSD 验证 NF-e/NFC-e 4.00 XML 文档。该 XSD 已应用 PL_010e_v.1.02 和 PL_010f_v.1.04 的差异补丁（本地“未签名”变体，见下文说明）。

参数	类型	必填	说明
`xml_content`	`string`	否*	XML 字符串
`xml_base64`	`string`	否*	Base64 编码的 XML

* 必须且只能提供 xml_content/xml_base64 其中之一。

返回 {"valid": bool, "errors": [...], "metadata": {"schema_version": ...}}。

[Inference]：官方 XSD（nfe_v4.00.xsd/leiauteNFe_v4.00.xsd，PL_010d）要求 <ds:Signature> 必须作为 <NFe> 的子元素。由于第一阶段生成未签名文档，此工具会使用本地派生副本（nfe_v4.00_unsigned.xsd）进行验证，其中 <ds:Signature> 已设为可选（minOccurs="0"）。验证已签名文档（未来阶段）时，应使用未经修改的官方 XSD。

`br__build_access_key`

根据组成部分 cUF、dhEmi、开具方 CNPJ、型号、系列和单据编号，生成带有模 11 校验位的访问密钥（chNFe，44 个字符）。

参数	类型	必填	描述
`c_uf`	`string`	是	IBGE 州代码（2 位）
`dh_emi`	`string`	是	开具日期/时间（ISO 8601）
`cnpj`	`string`	是	开具方 CNPJ（数字或字母数字 PL_010d）
`modelo`	`string`	是	`55`（NF-e）或 `65`（NFC-e）
`serie`	`string`	是	单据系列
`nnf`	`string`	是	单据编号
`tp_emis`	`string`	否	开具类型（默认值为 `"1"`）
`c_nf`	`string`	否	随机数字代码（cNF，8 位）；省略时自动生成

返回 {"chave_acesso": ..., "cnf": ...}。

CT-e（型号 57）工具

CT-e（Conhecimento de Transporte Eletrônico）支持始于 v0.6.0。v1 的范围有意保持精简：仅支持公路运输方式（其他运输方式会报错），仅支持 ICMS CST 00（正常征税），且不附带/验证 SEFAZ CT-e 端点表——以下每次 SEFAZ 调用都必须显式指定 endpoint_override。从 v0.7.0 起，br__generate_cte 还支持 NT 2026.002 引入的消费税制改革（IBS/CBS）字段——imp/IBSCBS、emit/ISUFEmit 和 ide/tpPagAnt+gPagAntecipado；NT 中自包含的业务规则由模型层强制执行，但需要查询实时 SEFAZ 数据库的规则不会检查。

`br__generate_cte`

根据 BRCTeDocument 对象生成未签名的 CT-e 4.00 单据（<CTe><infCte>…</infCte></CTe>）。

参数	类型	必填	描述
`cte`	`object`	是	`BRCTeDocument`（型号 57、公路运输方式、ICMS CST 00）

返回 {"xml": ..., "chave_acesso": ..., "warnings": [...]}。

`br__validate_cte_xml`

根据附带的 PL_CTe_400 XSD 验证 CT-e 4.00 XML 单据（根据是否存在 <ds:Signature> 自动选择未签名或官方签名架构）。

参数	类型	必填	描述
`xml_content`	`string`	否*	XML 字符串
`xml_base64`	`string`	否*	Base64 编码的 XML

* 必须且只能提供 xml_content/xml_base64 中的一个。

`br__consult_cte_sefaz_status`

检查 SEFAZ CT-e Web 服务的可用性（CTeStatusServicoV4）。只读，无需确认。

`br__consult_cte`

通过访问密钥查询 CT-e 状态（CTeConsultaV4）。只读，无需确认——它查询的是一份已知单据，而不是批量提取数据。

`br__submit_cte`

将已签名的 CT-e 提交至 SEFAZ 授权服务（CTeRecepcaoSincV4，同步）。根据 CT-e MOC 的要求，传输前会自动对载荷进行 GZip 压缩并进行 Base64 编码。此操作受双步确认（ConfirmationGate）和 BR_CTE_READ_ONLY 限制。

`br__cancel_cte`

请求取消已获授权的 CT-e（事件 110111，CTeRecepcaoEventoV4）。cStat=135 表示取消已获核准。此操作受限制。

`br__correct_cte`

签发 Carta de Correção Eletrônica（电子更正函；事件 110110，CTeRecepcaoEventoV4）。根据 CONVÊNIO/SINIEF 06/89 第 58-B 条，CC-e 不得更改税额、交易方注册数据或开具/出发日期。此操作受限制。

尚未实现：br__distribute_cte_dfe（CTeDistribuicaoDFe）——附带的规范确认了请求载荷的结构，但未确认 Web 服务的方法名称、WSDL 命名空间或消息包装元素。

架构

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

与 `mcp-einvoicing-core` 的关系

mcp-einvoicing-core 提供：

发票、相关方、行项目和验证结果的基础 Pydantic 模型（InvoiceDocument、InvoiceLineItem、TaxIdValidationResult）
共享的 MCP 服务基础设施（EInvoicingMCPServer）
HTTP/OAuth2 客户端、令牌缓存、结构化日志记录和异常体系

mcp-nfe-br 添加了巴西特定逻辑：

BRInvoice（扩展 InvoiceDocument，因为 NF-e/NFC-e 与 EN 16931 没有继承关系）
BRInvoiceLine 中的 I 组字段（NCM、CFOP、ICMS/IPI/PIS/COFINS）
CPF/CNPJ 验证（包括 NT 2026.004 中的字母数字 CNPJ）

供应商中立性

此服务自行实现标准：在本地构建、验证和签署文档。它不是商业发票平台的客户端，你的签名密钥和凭据绝不会离开你自己的基础设施。

发票会使用你自己的数字证书，直接发送至 SEFAZ（NF-e/NFC-e）和 CT-e SEFAZ 端点，不涉及任何中间方。

贡献

欢迎贡献。在提交拉取请求之前，请先创建议题讨论重大更改。

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

其他电子发票 MCP 服务

国家/地区	服务
🌍 全球	mcp-einvoicing-core
🇧🇪 比利时	mcp-einvoicing-be
🇧🇷 巴西	mcp-nfe-br
🇫🇷 法国	mcp-facture-electronique-fr
🇩🇪 德国	mcp-einvoicing-de
🇮🇳 印度	mcp-einvoicing-in
🇮🇹 意大利	mcp-fattura-elettronica-it
🇲🇽 墨西哥	mcp-cfdi-mx
🇵🇱 波兰	mcp-ksef-pl
🇸🇬 新加坡	mcp-invoicenow-sg
🇪🇸 西班牙	mcp-facturacion-electronica-es
🇦🇪 阿联酋	mcp-einvoicing-ae

许可证

本项目采用 Apache 2.0 许可。详情请参阅 LICENSE。完整的版本历史请参阅 CHANGELOG.md。

支持 Markdown

登录后评论

基本信息

作者: cmendezs
语言: python
版本: 0.9.1
传输方式: stdio
收录时间: 2026年9月12日
最近更新: 7 周前
官方 Registry: io.github.cmendezs/mcp-nfe-br

报告问题

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

mcp-nfe-br

关于 mcp-nfe-br

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

mcp-nfe-br 🇧🇷

简介

安装

要求

使用 uv（推荐）

使用 pip

从源码安装

配置

环境变量

Claude Desktop 集成

Cursor 集成

Kiro 集成

可用工具

br__validate_cpf

br__validate_cnpj

br__generate_nfe

br__validate_nfe_xml

br__build_access_key

CT-e（型号 57）工具

br__generate_cte

br__validate_cte_xml

br__consult_cte_sefaz_status

br__consult_cte

br__submit_cte

br__cancel_cte

br__correct_cte

架构

与 mcp-einvoicing-core 的关系