mcp-brasil：把 70 个巴西公共数据源塞进一个 MCP Server

它解决的是巴西公共数据的接入摩擦，不是数据质量问题

巴西的公开数据分散在几十个机构各自的 API 里：Banco Central 的 SGS 时间序列、Câmara dos Deputados 的提案与投票、Portal da Transparência 的合同与支出、各州 TCE 的财政数据、TSE 的选举档案。每个接口的认证方式、分页约定、字段命名和限流策略都不一样。mcp-brasil 做的事情是把这些差异收进一层统一的 tool 接口，让 LLM 通过函数调用去访问，而不是让使用者逐个读文档写请求代码。

目标用户很明确：做巴西政务、财经或调查报道方向的 agent 应用开发者，以及需要在对话里直接查证巴西公开数据的分析人员。README 给出的示例问题都是这类场景，比如查 2024 年 Câmara 关于人工智能的立法提案及作者，或者比较 São Paulo 与 Minas Gerais 的人均医疗支出。

需要说清楚的是，项目本身声明它不是巴西政府或任何被引用机构的官方服务。它只做转发和格式转换，数据的准确性、时效性和可用性取决于上游。README 里那句关于 MIT 许可只覆盖代码的提示值得认真对待。

533 个工具靠目录自动注册，靠 BM25 做上下文筛选

这么大规模的工具集如果全部塞进模型的上下文，token 消耗和选择准确率都会崩。项目用两个机制处理这个问题。

第一个是 auto-registry。README 的说法是「adicionar uma feature é criar uma pasta」，也就是新增一个数据源等于新建一个目录，不需要改中心化的注册表。这解释了为什么它能堆到 70 个 feature：每个 feature 目录自带自己的 tools 定义，启动时被扫描进来。代价是工具命名和参数风格的一致性要靠约定维持，而不是靠类型系统强制。

第二个是 smart discovery，用 BM25 search transform 把 533 个 tools 过滤成与当前上下文相关的子集再暴露给模型。BM25 是词袋检索，对「Selic」「IPCA」「licitação」这类专有名词效果直接，但对语义改写较弱的查询可能召回不准。这是文档里给出的机制描述，实际召回表现需要你自己在目标场景里验证。

在此之上还有两个组合型工具：planejar_consulta 用来生成跨 API 的执行计划，比如把某位议员的支出、投票记录和提案组合成一次查询；executar_lote 用来在一次调用里并行触发多个查询。这两个工具是项目区别于「一堆 HTTP 包装」的地方，也是它想解决 cross-reference 场景的直接体现。

大数据集走 DuckDB 本地缓存，且需要显式开启

不是所有数据都适合实时转发。README 列出的几个数据集体量明显超出普通 API 调用的范围：SIAPA 约 81.3 万个不动产记录，TSE 2014 到 2024 年的候选人、资产、得票、社交账号与 FEFC 数据，ANP 的燃油价格，INEP 的学校普查与 ENEM，ISP-RJ 的公共安全数据，ANAC 的航空器与定期航班。

对这些数据的处理方式是把它们落到本地，用嵌入的 DuckDB 执行 SQL 查询。README 明确写了这是 opt-in，通过环境变量开启。这个设计判断是合理的：DuckDB 在单机上对列式聚合查询的表现通常好过反复打远端 API，而且避开了上游的分页限制。

但 opt-in 也意味着默认状态下这些 feature 不可用，使用者需要自己承担首次同步的时间和磁盘占用。README 没有在给出的部分说明同步是全量还是增量、失败后如何恢复、数据多久过期。这几个问题在决定是否把它用于长期运行时必须先查清楚，因为本地缓存的陈旧程度会直接影响查询结果的可信度。

安装是 uvx 一行，配置成本主要在密钥和数据源许可

代码分发走 PyPI，pip install mcp-brasil 或 uv add mcp-brasil 都可以。接入客户端的方式按平台分几种。

Claude Code 最简单，一条命令：

claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server

Claude Desktop 和 Google Antigravity 需要写 JSON 配置。Antigravity 的配置在 MCP Servers 菜单里通过 View raw config 打开，或者直接编辑 ~/.gemini/config/mcp_config.json（全局）与 .agents/mcp_config.json（工作区）。Claude Desktop 编辑 claude_desktop_config.json。两处的结构一致：

{ "mcpServers": { "mcp-brasil": { "command": "uvx", "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"], "env": { "TRANSPARENCIA_API_KEY": "sua-chave-aqui", "DATAJUD_API_KEY": "sua-chave-aqui", "META_ACCESS_TOKEN": "seu-token-aqui" } } } }

VS Code 和 Cursor 用 .vscode/mcp.json，注意顶层键是 servers 而不是 mcpServers。需要 HTTP 传输的客户端可以跑：

fastmcp run mcp_brasil.server:mcp --transport http --port 8000

服务暴露在 http://localhost:8000/mcp。

密钥方面，README 的统计是 66 个 API 不需要密钥，4 个需要免费注册的密钥，涉及 TRANSPARENCIA_API_KEY、DATAJUD_API_KEY 和 META_ACCESS_TOKEN。同一份文档在 Quick Start 注释里又写成「没有密钥时其余 36 个 API 正常工作」，与前面的 66 这个数字对不上。这种内部不一致在快速迭代的项目里常见，但配置前最好以实际启动后的工具列表为准。

真正需要花时间的不是安装，是许可。SOURCES.md 逐个列出每个数据源的许可，ACCEPTABLE_USE.md 规定服务本身的使用边界。README 明确要求在商业、新闻或决策用途之前阅读这两份文件。这不是形式化的免责声明，因为不同政府数据源对再分发和商用的态度确实不同。

上游 API 的稳定性不在这层封装的控制范围内

最直接的失败模式是上游变更。533 个 tools 背后是 70 个由不同机构维护的接口，任何一家调整字段名、改认证方式、下线端点或加严限流，对应的 tool 就会失效。项目能做的是用 httpx async 加 Pydantic v2 做响应校验，以及用带 backoff 的限流策略缓解瞬时错误，但 schema 变更导致的解析失败只能等维护者跟进。

第二个限制是覆盖不均。README 的表格显示，transparencia 一个 feature 就有 54 个 tools，senado 有 26 个，而 tce_sc 只有 2 个，tce_to 有 3 个。同样是州审计法院，能力密度差了一个数量级。如果你的分析对象正好落在工具数少的那几个州，能问的问题会明显受限。

第三个是它不适合当数据管道。这是一个面向交互式 agent 调用的 MCP Server，不是带重试队列、幂等写入和血缘追踪的 ETL 组件。想要把巴西公共数据定期同步进数据仓库，用它的价值不大，直接对接上游 API 更可控。

另外，项目主页字段为空，没有独立文档站点，README 是主要信息源，发布节奏偏快（v0.12.1 到 v0.14.0 集中在 2026 年 4 月）。快速迭代加上 70 个上游依赖，意味着版本间的行为变化需要留意。

与直接写 API 客户端或自建工具层的区别

最常见的替代方案是自己针对需要的几个数据源写请求代码，再包成 agent 的 tool。这条路在只涉及两三个 API 时完全合理，代码量不大，字段映射也由你控制。区别出现在覆盖面扩大之后：当你需要同时查 Câmara 的支出、TCU 的裁决和 TSE 的竞选资金，并且希望模型自己决定调用顺序时，自建方案的维护成本会随数据源数量线性增长，而 mcp-brasil 把这些成本压到了一个依赖上。

另一类是通用 HTTP 请求工具，让模型自己拼 URL 和解析 JSON。这种方案对 API 文档质量的要求极高，而巴西各机构的文档规范程度差异很大，模型很容易在分页参数或日期格式上出错。mcp-brasil 的 Pydantic 模型在这里起到了约束作用。

真正接近的对比对象是其他国家的同类 MCP 数据封装项目。区别在于 mcp-brasil 面对的是巴西特有的数据版图：联邦、州、市三级财政数据分属不同审计法院，选举数据集中在 TSE，立法数据分属 Câmara 和 Senado。它选择的是广度优先，把 70 个源都纳进来，而不是把少数几个源做深。这个取舍决定了它在任何单一数据源上的能力都不如专门针对该源的封装。

维护成本与许可边界

代码是 MIT，可以自由使用、修改和再分发。但 README 反复强调 MIT 只覆盖代码，每个数据源有自己的许可，使用服务本身还受 ACCEPTABLE_USE.md 约束。这意味着你不能因为项目是 MIT 就假定它转发出来的数据可以任意使用。涉及商业用途或公开发布的分析结果时，需要回到 SOURCES.md 逐个确认对应数据源的条款。这里不构成法律意见，具体判断应咨询专业人士。

维护成本分两块。一块是项目本身的版本跟进，考虑到发布频率，建议固定版本号而不是跟随最新。另一块是上游漂移带来的隐性成本：即使你不升级 mcp-brasil，某个政府 API 改了字段也可能让你的查询突然失败。这是所有聚合型封装的固有代价。

项目还声明它不是任何巴西政府机构的官方服务。如果你的使用场景需要数据来源的官方背书，比如正式的审计或法律用途，这一点需要提前考虑，直接引用原始机构的数据出口会更稳妥。

编辑结论

适合已经在用 Claude Desktop、Claude Code、Cursor 或 Google Antigravity，并且需要巴西立法、财政、司法、选举数据的团队；不适合把它当成稳定数据管道或需要 SLA 的生产依赖。上手前先读 ACCEPTABLE_USE.md 和 SOURCES.md，确认目标数据源的使用条款；再检查你要用的 feature 是否落在需要密钥的 4 个 API 里，以及是否需要开启 DuckDB 本地缓存来查询 TSE 或 SIAPA 这类大数据集。

官方来源

1. Issues
2. License: MIT
3. Mcp-Brasil/mcp-brasil on GitHub
4. README
5. Releases