fiscal

---

简介

Brasil NFe MCP 是首个 MCP（Model Context Protocol）服务，它将巴西完整的税务基础设施作为工具、资源和提示词开放给任何兼容 MCP 的客户端使用——包括 Claude Desktop、Cursor、Windsurf、VS Code Copilot、Zed、Continue.dev、JetBrains，或你自己的应用。

将服务接入 MCP 客户端后，AI Agent 就能在对话中通过自然语言开具发票——“为这个 CPF 开具一张金额为 R$ 89,90 的 NFC-e”——然后将单据发送给 SEFAZ。AI 会自行发现工具，根据 schema 构建 payload，并将 SEFAZ 错误转换成清晰易懂的语言。

REST API 还是 MCP？

两者都是 Brasil NFe 一流的产品，开放的是同一套税务基础设施——同一个 SEFAZ 后端、同一份 SLA、同样的人工支持。选择取决于集成方式，而非质量：

适合使用 REST API 的场景	适合使用 MCP 的场景
你有 ERP、管理系统或自有应用，且开具流程已确定	你希望由 AI 助手、copilot 或 Agent 决定何时以及如何开具
处理任务是批量、定时执行，或由队列/webhook 事件触发	流程以对话方式进行——用户（或 Agent）参与其中并引导每一步
集成过程是确定性的，且你能精确控制 UI/UX	客户希望将会计师的 Claude / Cursor / Copilot 直接接入业务
高并发量、优化的并行处理、稳定的 payload 合约	通过自然语言进行交互式、探索式、临时性会话

两者连接到同一个后端——你可以通过 REST 集成 ERP，同时将会计师的 AI 接入 MCP。REST API 新增路由后，它会自动成为 MCP 工具。统一的税务路线图，两个使用渠道。

公共端点

https://api.brasilnfe.com.br/services/Mcp

资源	方法	路径
JSON-RPC	POST	/services/Mcp
SSE 流	GET	/services/Mcp
结束会话	DELETE	/services/Mcp
发现	GET	/.well-known/mcp
健康状态	GET	/services/Mcp/info

• 传输： Streamable HTTP
• 规范： MCP 2025-06-18
• 身份验证： Bearer token（Authorization: Bearer <TOKEN>）
• 速率限制： 每个 token 每分钟 60 个请求（默认）

开放内容

30 多个工具，分为 8 个类别

类别	工具	功能
NF-e / NFC-e	nfe_emitir, nfe_emitir_complementar, nfe_previsualizar	开具 B2B 商品发票（型号 55）或零售收据（型号 65），生成预览版 DANFE
NFS-e	nfse_emitir, nfse_consultar	开具和查询服务发票（内置 5,500 多条市政规则）
CT-e	cte_emitir, cte_desacordo	开具运输单据，登记收货方的异议
MDF-e	mdfe_emitir, mdfe_encerrar	开具货运清单，在运输结束时关闭清单
DC-e	dce_emitir	开具内容声明（个人 / MEI）
NF-EnerCom	nfenercom_gerar_arquivo, nfenercom_emitir	开具商业能源发票
税务事件	evento_cancelar, evento_carta_correcao, evento_manifestar, evento_inutilizar	取消、纠正（CC-e）、收货方确认、作废编号
SEFAZ 查询	sefaz_status, cadastro_consultar, nota_listar, imposto_calcular	服务状态、IE、发票列表、税费模拟器
登记信息	cliente_consultar/criar/editar, produto_consultar/criar/editar, tributacao_consultar/criar/editar	完整的客户、产品和税务规则 CRUD（并提供 Receita Federal 回退机制）
文件	arquivo_baixar, arquivo_baixar_evento, arquivo_baixar_periodo	下载单个 XML / PDF 或指定期间的 ZIP 文件
辅助工具	fci_gerar, health	生成 FCI（进口内容），运行健康检查

5 个资源（URI scheme brasilnfe://）

• brasilnfe://empresa/atual - 已登录企业快照
• brasilnfe://nfe/{chave}/xml - 已授权 XML
• brasilnfe://nfe/{chave}/danfe - PDF 格式的 DANFE
• brasilnfe://evento/{chave}/{seq} - 按序号查询事件
• brasilnfe://recebidas/{periodo} - 指定期间收到的发票

5 个现成提示词

• emitir_nfe_simples - NF-e 开具引导流程
• cancelar_nota - 带期限验证的发票取消流程
• diagnostico_emissao - 开具前的全面检查
• relatorio_periodo - 期间税务报告
• carta_correcao - 带允许字段验证的 CC-e 流程

快速开始

1. 获取令牌

在 brasilnfe.com.br 创建免费账户，并从控制面板复制令牌。沙盒模式免费——你可以随意开具测试文件，不会有任何内容发送到生产环境的 SEFAZ。

2. 配置 MCP 客户端

从 examples/ 中选择正确的文件，并粘贴到客户端配置中：

• Claude Desktop
• Cursor
• Windsurf
• VS Code Copilot
• Zed
• 纯 cURL（JSON-RPC）

将 SEU_TOKEN_AQUI 替换为实际令牌，然后重启客户端。

3. 与 AI 对话

"Liste o status da SEFAZ pra SP."
"Consulte o CNPJ 39.658.743/0001-99."
"Emite uma NFC-e de R$ 89,90 pro consumidor com CPF 123.456.789-00."
"Cancela a chave 35..., justificativa: erro de digitação no valor."

完成。AI 会自动发现工具，询问缺少的信息、进行验证、构建 payload、发送到 SEFAZ，并向你提供密钥、协议、XML 和 PDF。

无需注册即可体验

打开 brasilnfe.com.br/ai，直接在浏览器中与税务助手对话。不会发送到生产环境的 SEFAZ，但你可以看到完整流程，并在聊天窗口旁实时渲染 DANFE。

最佳实践

• 务必先在沙盒环境（tipoAmbiente: 2）中运行，再用于生产环境。 测试文件使用允许的 CNPJ，并采用独立编号——没有税务风险。
• 创建前先查询客户 / 产品 / 税务信息。 *_consultar 工具可避免重复，并为 AI 提供上下文，以便复用现有登记信息。
• 确认破坏性操作。 取消和作废操作不可逆——AI 已被指示要求确认，但仍请在自己的工作流中进行核查。
• 关闭空闲会话。 DELETE /services/Mcp 可更早释放配额。
• 自动生成审计记录。 所有 MCP 调用都会在企业控制面板中记录并保存 5 年（符合 LGPD 要求）。

支持

• 文档： brasilnfe.com.br/mcp
• 在线演示： brasilnfe.com.br/ai
• WhatsApp： +55 (31) 9 7168-5947（工作时间）
• 电子邮件： [email protected]（24/7）
• LGPD/DPO： [email protected]

关于

由 Brasil NFe LTDA（CNPJ 39.658.743/0001-99）维护。该公司于 2019 年由 Maxsuel Lima 在 Ipatinga/MG 创立，是巴西税务自动化领域的专家：覆盖 6 种税务单据，包含 5,500+ 条 NFS-e 市政规则、543 个 SEFAZ 内置代码，符合 PCI DSS 标准，并提供 24/7 人工支持。

许可证

MIT - 您可以自由使用、修改和分发此仓库（配置、示例和文档）。MCP 服务本身由 Brasil NFe LTDA 运营——请参阅使用条款和隐私政策。