MCP Fiscal Brasil

社区

面向巴西税务系统的 MCP 服务器：CNPJ、NF-e、SPED、eSocial 与 2026 税改（IBS/CBS），零注册、离线表。

★ 295 Stars 分类 · 其他非常热门

67FMRS · C

MCP Fiscal Brasil 是一个聚焦巴西税务（fiscal）垂直领域的 MCP 服务器，覆盖面较广：从 CNPJ/CPF 校验、Simples/MEI 查询，到 NF-e 解析、DANFE 生成、XMLDSig 签名校验、SPED/eSocial 分析、离线税表以及 2026 税改（IBS/CBS）模拟，共约 44 个工具，并额外提供 CLI、REST API 与 Python SDK。其最大特点是无需账户或 API key 即可使用大部分功能，且大量处理在本地离线完成。需要 SEFAZ 实时交互的功能必须自备 A1 证书，属可选启用且证书不出本机。适合巴西会计、ERP 与财务自动化团队；不适合非巴西税务场景，也不应被视为任何政府机构的官方项目。使用时需注意第三方数据源稳定性与税务建议的参考性质。

可靠性

11/20

安全与权限

14/20

维护活跃度

14/20

文档质量

13/20

安装易用性

15/20

查看 FMRS 评分方法 →

MCP Fiscal Brasil 是一个巴西税务垂直领域的 MCP 服务器（Python，MIT 许可，通过 PyPI 包 mcp-fiscal-brasil 以 uvx 运行，stdio 传输，约 44 个工具）。它把 CNPJ、CPF、Simples Nacional/MEI、NF-e、NFS-e、SPED、eSocial、税务凭证等查询封装为可组合的工具，供 Claude Desktop、Claude Code、Cursor、VS Code + Continue 等 MCP 客户端调用。多数工具无需任何 API key 即可使用：CNPJ 与 Simples Nacional 通过 BrasilAPI，NF-e 的解析、DANFE 生成、XMLDSig 签名校验、SPED/eSocial 分析以及 NCM/CFOP/CST/CEST 等离线参考表均在本地完成。部分工具（consultar_status_sefaz、baixar_nfe_distribuicao、manifestar_nfe）需要本地 A1 数字证书（.pfx/.p12）以进行 SEFAZ 的 mTLS 交互，属可选启用。另有若干工具只返回政府门户 URL 或带明确局限（如按名称搜索 CNPJ）。注意：该服务器由 DeHor-Labs 维护，并非 MCP 协议或任何政府机构的官方项目。

工具能力

analyze_cnpj_compliance

生成单个 CNPJ 的税务合规综合报告（CNPJ + Simples/MEI + CNAE）。

risk_score_supplier

对供应商给出 0-100 风险评分、风险等级、影响因素与是否建议合作的结论。

consultar_empresas_lote

一次查询多个 CNPJ，按企业返回合规信息与评分，并带逐条错误。

compare_tax_regimes

按给定场景比较 MEI、Simples Nacional、Lucro Presumido 与 Lucro Real 等税制。

validate_nfe_full

基于 XML 对整个 NF-e 做完整校验（XML、访问键、签发方），返回结构化问题列表。

summarize_sped

把 SPED 文件转成执行摘要：期间、企业、数据块与不一致项。

consultar_cnpj

查询完整 CNPJ 数据：公司名称、股东、CNAE、地址等（经 BrasilAPI）。

consultar_simples_nacional

查询是否为 Simples Nacional/MEI 纳税人，含加入与退出日期（经 BrasilAPI）。

validar_chave_nfe

离线校验 44 位 NF-e 访问键的校验位，并解析出 UF、CNPJ、日期与编号。

consultar_nfe

通过 44 位访问键查询完整 NF-e（经 BrasilAPI）。

parse_nfe_xml

离线解析 NF-e/NFC-e 原始 XML，返回结构化数据。

gerar_danfe

离线根据 NF-e（型号 55）XML 生成 A4 版 DANFE PDF。

validar_assinatura_nfe

离线校验 XMLDSig 签名并提取证书中的信息。

consultar_status_sefaz

通过 NfeStatusServico4 查询各州 SEFAZ Web 服务实时状态（需 A1 证书）。

baixar_nfe_distribuicao

通过 NFeDistribuicaoDFe 下载文档（需本地 A1 证书）。

manifestar_nfe

通过 NFeRecepcaoEvento 以收件人身份对 NF-e 进行事件申报（需 A1 证书）。

validar_cpf

离线校验 CPF 校验位。

analisar_sped

离线分析 EFD/ECD/ECF 文件：期间、企业、错误。

listar_registros_sped

按类型（如 C100、E110）筛选 SPED 记录。

listar_eventos_esocial

按分组筛选的 eSocial 事件目录。

validar_evento_esocial

对 eSocial 事件 XML 结构做基础校验。

consultar_nfse

返回所在城市的 NFS-e 门户 URL 与所用系统（需人工在门户操作）。

consultar_certidao_federal

返回用于开具联邦 CND 的 e-CAC URL。

consultar_certidao_fgts

返回用于查询 CRF 的 Caixa 门户 URL。

listar_cnpjs_por_nome

实验性：按名称搜索 CNPJ；巴西联邦税务局并未公开提供按名称搜索的 API，覆盖有限。

安装接入

安装 uv（若尚无）：curl -LsSf https://astral.sh/uv/install.sh | sh。2. 最简单的运行方式：uvx mcp-fiscal-brasil；如需保持最新，使用 uvx mcp-fiscal-brasil@latest 或 uvx --refresh mcp-fiscal-brasil（uvx 会缓存版本）。3. 配置客户端，例如 Claude Desktop：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），写入 {"mcpServers":{"fiscal-brasil":{"command":"uvx","args":["mcp-fiscal-brasil"]}}} 后重启。4. Claude Code 可用：claude mcp add fiscal-brasil -- uvx mcp-fiscal-brasil。5. Cursor 可写入 .cursor/mcp.json 或项目根 .mcp.json；VS Code + Continue 写入 settings.json 的 continue.mcpServers。6. 也可用 Docker（ghcr.io/dehor-labs/mcp-fiscal-brasil:latest，-i 方式）或 pip install mcp-fiscal-brasil。所有环境变量（如 MCP_FISCAL_LOG_LEVEL、BRASILAPI_BASE_URL、HTTP_TIMEOUT）均为可选。

claude_desktop_config.json

{
  "mcpServers": {
    "fiscal-brasil": {
      "command": "uvx",
      "args": ["mcp-fiscal-brasil"]
    }
  }
}

生成并校验客户端配置

选型与风险

适合谁

面向巴西市场的会计、ERP、CRM 与财务自动化团队。
需要对 NF-e/SPED 做本地离线处理、不希望把 XML 上传到第三方服务的开发者。
使用 Claude/Cursor 等 MCP 客户端、希望用自然语言查询巴西税务数据的用户。
需要 NCM/CFOP/CST/CEST/ICMS 及 BCB 指数等离线参考表的人群。

不适合谁

需要美国或其他非巴西税务能力的用户。
期望官方政府机构背书或官方 MCP 项目的用户（本服务器由 DeHor-Labs 维护，非官方）。
希望在不配置 A1 证书的前提下查询 SEFAZ 实时状态或做分发/申报的用户。
需要按公司名称搜索 CNPJ 的大规模检索场景（该能力为实验性且覆盖有限）。

所需权限

作为 MCP 服务在本地以标准输入输出（stdio）运行，不需要账户或 API key。
网络访问：调用 BrasilAPI（cnpj、nfe 等）以及可选的 ReceitaWS 回退。
可选启用 A1 数字证书：需读取本地 .pfx/.p12 文件及其密码，用于 SEFAZ 的 mTLS 与 XMLDSig 签名。
可选环境变量：MCP_FISCAL_LOG_LEVEL、BRASILAPI_BASE_URL、HTTP_TIMEOUT，以及 NFE_CERTIFICADO_PATH、NFE_CERTIFICADO_SENHA、NFE_EMITENTE_CNPJ、NFE_AMBIENTE。

风险与副作用

第三方数据源（BrasilAPI、ReceitaWS、SEFAZ）可能不稳定或变更，导致查询结果过时或失败。
启用 A1 证书后，证书文件与密码是本机敏感资产：应按文档要求通过密钥管理器注入，切勿把明文密码提交到版本库。
工具返回的税务信息与建议（如风险评分、税制比较）可作为参考，但不能替代专业会计师或法律意见。
consultar_status_sefaz 在未配置证书时会抛出 FiscalConfigurationError，HTTP 端点返回 503，需与 SEFAZ 实际故障区分开。
实验性工具 listar_cnpjs_por_nome 覆盖有限，结果可能不符合预期。

常见排障

工具未出现在客户端中：确认重启了 MCP 客户端，并检查 JSON 配置路径与语法是否正确。
版本过旧：uvx 会缓存，改用 uvx mcp-fiscal-brasil@latest 或 uvx --refresh mcp-fiscal-brasil。
找不到 uvx：先安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh），或改用 pip install mcp-fiscal-brasil 后以 mcp-fiscal-brasil 作为命令。
SEFAZ 状态查询报配置错误或 HTTP 503：说明未配置 NFE_CERTIFICADO_PATH/NFE_CERTIFICADO_SENHA，或证书无效；配置证书后重试。
网络类查询失败：检查到 BrasilAPI 的连通性、HTTP_TIMEOUT 设置，必要时用 BRASILAPI_BASE_URL 指向自定义环境。
日志排查：把 MCP_FISCAL_LOG_LEVEL 设为 DEBUG 获取更多信息。

使用场景

供应商尽职调查与批量筛查：用 risk_score_supplier 与 consultar_empresas_lote 评估合作风险。

CNPJ 合规核查：用 analyze_cnpj_compliance 汇总公司、Simples/MEI 与 CNAE 信息。

NF-e 处理：离线解析 XML、生成 DANFE、校验 XMLDSig 签名与访问键。

SPED 与 eSocial 的离线分析与结构校验。

税制选择比较：用 compare_tax_regimes 对比 MEI、Simples、Lucro Presumido 与 Lucro Real。

在应用代码中通过 Python SDK 或 CLI（mcp-fiscal）直接调用税务能力。

支持客户端

Claude Desktop完整支持

Claude Code完整支持

Cursor完整支持

VS Code + Continue完整支持