MCP Fiscal Brasil

社区

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

分类: 其他第 25 / 230
Stars: ★ 324 非常热门
传输方式: stdio（本地进程）
运行环境: Python 3.10+ · Docker
凭据: 可选 API Key
许可证: MIT
最近提交: 6 天前
工具数: 25

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 与财务自动化团队；不适合非巴西税务场景，也不应被视为任何政府机构的官方项目。使用时需注意第三方数据源稳定性与税务建议的参考性质。

最强项 · 安装易用性 15/20 最弱项 · 可靠性 11/20

可靠性

11/20

安全与权限

14/20

维护活跃度

14/20

文档质量

13/20

安装易用性

15/20

查看各项评分依据

可靠性 11/20: 清单与 README 描述了 stdio 传输、uvx 运行时和 44 个工具，工具命名与描述自洽，离线校验类工具（CPF/CNPJ/NF-e 校验、SPED 解析）逻辑上可复现。但本次审查仅有 server.json 与 README，未提供任何源码文件、测试或 CI 工作流日志；README 提及的 85% 覆盖率与 CI 徽章属于不可验证的自我声明，静态校准下不构成执行证据。证书类工具（consultar_status_sefaz 等）在无证书时的错误语义有说明（FiscalConfigurationError / 503），属可控失败，是加分点。按校准，缺少可验证证据与测试细节，最高不超过 12，取 11。
安全与权限 14/20: 未触发红线：无恶意代码、无凭据窃取、无隐蔽外发。证书 A1 与密码由用户本地提供，README 明确说明 mTLS 与 XMLDSig 在本地完成、证书与密码不发送到外部服务器，且要求密码走密钥管理而非版本化 .env；脱敏端点仅返回是否配置有效证书，不暴露身份。只读为主的咨询类操作，无不可逆删除/支付/部署默认行为。扣分点：出站网络调用（BrasilAPI、ReceitaWS、SEFAZ）仅以文字披露，未见最小权限或确认机制的具体实现证据；签署/下载文档类 mTLS 操作无显式确认流程说明；数据流披露依赖 README 单一来源。故给 14。
维护活跃度 14/20: MIT 许可证明确，版本号在 manifest 与 README 间一致（0.5.1），有 CHANGELOG、Roadmap（含已完成与待办版本）、Discussions、Newsletter 与发布自动化提及，295 stars / 12 open issues 显示活跃度。扣分点：无源码可见，无法核实提交频率、issue 响应、依赖更新与安全响应渠道的实际运作；v1.0.0 SLA 仍为未完成项。故给 14。
文档质量 13/20: 文档层次较全：快速开始、各客户端配置示例（Claude Desktop/Code、Cursor、VS Code+Continue、Docker）、环境变量表、工具分类（功能性/指导/证书/实验性）并标注限制（如按名称查 CNPJ 无公开 API）、证书配置与失败语义、SDK/CLI/REST 多模式用法。扣分点：全部工具未给出参数签名与返回结构级说明，成本/限流边界含糊；README 中的演示输出为示例而非可复核证据；与其它项目的对比表属营销性自述，无法验证。故给 13。
安装易用性 15/20: 安装路径清晰且步数少：uvx mcp-fiscal-brasil 一行即可运行，附 uv 安装说明、@latest 刷新提示，且覆盖主流客户端配置片段与 Docker 运行方式，无需 API key。属主流客户端可用的简洁安装。扣分点：无文件内可验证的执行证据（无真实 CI/测试文件可见），按校准安装分不超过 15；离线安装与服务端主机/平台兼容性细节未完全展开。故取上限 15。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络

适合谁

面向巴西市场的会计、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 覆盖有限，结果可能不符合预期。

安装接入

准备工作

运行环境：Python 3.10+ · Docker

NFE_CERTIFICADO_SENHA 可选密钥证书密码，应通过密钥管理器提供而非写入版本库 .env，可选（密钥）。

其他可选配置项（6 个）

MCP_FISCAL_LOG_LEVEL 可选日志级别（DEBUG/INFO/WARNING），默认 INFO，可选。

BRASILAPI_BASE_URL 可选 BrasilAPI 的基础 URL，供自定义环境使用，默认 https://brasilapi.com.br/api，可选。

HTTP_TIMEOUT 可选 HTTP 请求超时秒数，默认 30，可选。

NFE_CERTIFICADO_PATH 可选本地 .pfx/.p12 A1 证书的绝对路径，仅 mTLS 相关工具需要，可选。

NFE_EMITENTE_CNPJ 可选证书持有者的 14 位 CNPJ，可选。

NFE_AMBIENTE 可选 SEFAZ 环境：producao 或 homologacao，默认 producao，可选。

安装 uv（若尚无）：curl -LsSf https://astral.sh/uv/install.sh | sh。
最简单的运行方式：uvx mcp-fiscal-brasil；如需保持最新，使用 uvx mcp-fiscal-brasil@latest 或 uvx --refresh mcp-fiscal-brasil（uvx 会缓存版本）。
配置客户端，例如 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"]}}} 后重启。
Claude Code 可用：claude mcp add fiscal-brasil -- uvx mcp-fiscal-brasil。
Cursor 可写入 .cursor/mcp.json 或项目根 .mcp.json；VS Code + Continue 写入 settings.json 的 continue.mcpServers。
也可用 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"]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

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

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add fiscal-brasil -- uvx mcp-fiscal-brasil

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

重启客户端后，工具列表中应出现 consultar_cnpj、validate_nfe_full 等 fiscal-brasil 工具；可直接询问 "Consulte o CNPJ 00.000.000/0001-91"，若返回企业数据（如 Banco do Brasil S.A.）即说明连接成功。

常见排障

工具未出现在客户端中：确认重启了 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 获取更多信息。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

查询 CNPJ 00.000.000/0001-91 并列出其股东
NFe 密钥 35240300623904000197550010000012341234567890 是否有效？
CNPJ 12.345.678/0001-90 这家企业属于 Simples Nacional 吗？
对 3524... 这份 NFe 的完整 XML 进行校验并列出所有问题

工具能力 25

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）。

展开其余 17 个工具

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，覆盖有限。

使用场景

供应商尽职调查与批量筛查：用 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

依据项目文档列出，未经本站实测。

详细介绍

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 协议或任何政府机构的官方项目。