mcp-fiscal-brasil – 面向AI代理的财政数据服务器

它是什么 – 一个基于Python的MCP（模型上下文协议）服务器，为AI助手、ERP、CRM和其他自动化工具提供对巴西复杂财政生态系统（CNPJ/CPF、NF-e、NF-Se、SPED、eSocial、Simples Nacional、2026年税改等）的即时、离线优先访问。核心功能无需API密钥或预先注册。

---

核心能力

领域	工具（高级）	低级原语
公司合规	analyze_cnpj_compliance, risk_score_supplier, consultar_empresas_lote	consultar_cnpj, consultar_simples_nacional
税务制度规划	compare_tax_regimes	–
发票处理	validate_nfe_full, summarize_sped	validar_chave_nfe, parse_nfe_xml, gerar_danfe, validar_assinatura_nfe
公共服务状态	–	consultar_status_sefaz
指导	–	consultar_nfse, consultar_certidao_federal, consultar_certidao_fgts

所有工具无需任何API密钥即可工作；可选的高级数据源（cpfcnpj.com.br）可通过令牌启用，以获取更丰富、实时的数据。

---

工作原理

1. 运行MCP服务器（或CLI / REST API）– 例如 uvx mcp-fiscal-brasil。
2. 配置您的AI客户端（Claude Desktop、Cursor、VS Code Continue等）指向 fiscal-brasil 服务器。
3. 用自然语言提问；服务器将其转换为适当的低级调用，从公共API（BrasilAPI、Receita WS）聚合数据，并在需要时执行离线XML解析或对SEFAZ的mTLS调用。
4. 响应以结构化JSON返回，AI可直接使用。

---

安装与快速开始

# 一次性执行（无需永久安装）
uvx mcp-fiscal-brasil

# 保持最新
uvx mcp-fiscal-brasil@latest   # 或 uvx --refresh …

或者通过pip/uv安装，或运行Docker镜像 ghcr.io/dehor-labs/mcp-fiscal-brasil:latest。

---

示例交互

您： 查询CNPJ 00.000.000/0001-91并列出股东。
AI： 公司：Banco do Brasil S.A.
     股东：União Federal (60.82%), BNDESPar (10.32%) …

您： NFe密钥 35240300623904000197550010000012341234567890 有效吗？
AI： 密钥有效！UF=SP，签发=03/2024，签发CNPJ=00.623.904/0001-97

您： 对于服务行业500k收入，哪种税务制度更有利？
AI： Compare_tax_regimes → Simples Nacional 税负最低（约12%）。

这些演示由高级工具 consultar_cnpj、validar_chave_nfe 和 compare_tax_regimes 驱动。

---

可选高级数据源

设置 CPFCNPJ_TOKEN（及相关环境变量）以启用 cpfcnpj.com.br API，该API增加：

• 实时官方数据（无延迟）
• 按密钥完整查询NF-e/NFC-e
• 更高级的合规数据 当令牌缺失时，服务器回退到免费数据源，因此基础产品保持免费。

---

适用对象

• AI助手开发者，需要为巴西客户提供现成的财政知识库。
• ERP/CRM集成商，希望添加税务合规检查而无需编写自定义SEFAZ连接器。
• 合规团队，希望快速获取风险评分或批量CNPJ审查。
• 开发者，希望使用单个Python包而不是处理数十个公共API。

---

路线图亮点

• 扩展市政NF-Se门户的覆盖范围。
• 添加更多实验性工具（例如，基于名称的CNPJ搜索）。
• 为REST接口提供完全类型化的OpenAPI规范。
• 改进缓存策略并添加Redis支持的插件。

---

许可证与社区

• MIT许可证 – 免费用于商业和非商业用途。
• 积极维护（CI徽章，测试覆盖率约85%）。
• 欢迎通过常规GitHub拉取请求工作流贡献。

---

底线： mcp-fiscal-brasil 是一个即插即用、零配置的服务器，将巴西臭名昭著的碎片化财政数据转化为干净、对代理友好的API，使AI助手能够开箱即用地回答税务相关查询。