MCP Brasil
让 AI 客户端通过 MCP 查询巴西政府与公共机构的数据。
证据显示大多数能力是对公共数据源的读取，API 密钥通过环境变量提供，大型本地数据集默认不启用，涉及 PII 的数据集另有 MCP_BRASIL_LGPD_ALLOW_PII 门控；部署工作流使用权限较窄的 OIDC，并保存旧版本用于失败回滚。README 还清楚区分代码 MIT 许可与各数据源许可，并反复声明项目非官方，因此来源归属获满分。扣分在于：未展示逐次用户确认机制，批量查询、网络请求、下载、缓存写入及强制刷新仍会产生外部或本地副作用；未说明密钥存储、日志脱敏或泄露响应；依赖仅设宽泛下限，所给证据没有依赖锁定、漏洞扫描或更新策略；回滚证据主要覆盖 Azure 部署，而非所有本地缓存或工具调用。
项目声明异步 HTTP、超时、最多重试三次和退避，并支持 Python 3.10 至 3.13，常用依赖与开发命令也有明确清单，因此普通依赖可用性处理较充分。扣分主要来自明显的内部数字冲突：同一 README 同时出现 533/525 个工具、70/69 个 feature，以及 66 无密钥加 4 有密钥、36 个剩余 API、62 个无密钥等不一致说法；架构计数也无法与总数直接吻合。材料未提供具体运行时错误消息、降级响应或用户可操作的故障示例，所以 failure_messages 仅有薄弱支持。
README 面向开发者、研究、新闻、司法、医疗和决策等多种场景，给出了按主题组织的能力目录、自然语言示例、多个 MCP 客户端配置、HTTP 方式、环境变量和可选数据集，受众与环境适配证据充分。能力边界通过非官方声明、数据许可区分、风险提示、可选密钥和数据集门控得到较好说明，但引用的 AUP 与详细指南未包含在材料中，部分边界无法核实。BM25 discovery、推荐工具与查询规划有助于触发精度，但没有提供工具 schema、冲突消解或误触发分析，因此未给满分。
信息架构、按 feature 打包方式、目录树、快速安装、客户端配置、开发命令和贡献流程都很清楚；MIT 文本与项目元数据一致，许可获满分。README 明确列出上游 API 不稳定、参数覆盖不全以及模型可能误解结果等限制，因此 known_limitations 获满分。扣分在于没有真正的 FAQ 或故障排查实例；名称大体稳定但功能与工具计数漂移削弱目录稳定性；pyproject 配置了语义发布和 CHANGELOG 路径，却未提供 CHANGELOG 内容；维护主体仅写作社区和 contributors，发布者又未经验证，缺少明确负责人、安全联系人或维护承诺。
该产品把大量分散的巴西公共 API、跨源规划、批处理、搜索发现和可选 DuckDB 数据集统一为 MCP 接口，静态证据显示明显的边际价值。自然语言示例、结构化 Pydantic 架构和多客户端接入支持输出可用性，但材料没有展示实际工具返回样例、字段稳定性或引用附带方式，因此未给满分。多数 API 无需密钥且安装简单，但大型数据集可能下载约 100MB 至 1.6GB、首次构建耗时数分钟，并可能产生 API 配额、存储和云部署成本，所以成本收益只属充分但非彻底。
大多数能力声明可追溯到按来源列出的功能表、配置表、架构说明、pyproject 元数据和两个部署工作流；关键法律与来源信息还指向 SOURCES、NOTICE 和 AUP。扣分在于这些被引用文件、工具实现、测试和锁文件并未提供，许多具体数量与覆盖范围只能依赖 README 自述，而且多处计数互相冲突。项目明确区分上游原始数据、服务器行为和下游模型的推断或幻觉，并要求高风险用途回查官方来源，因此事实与推断分离获满分。
- README 的工具、feature 和免密钥 API 数量互相矛盾；在依赖覆盖范围或容量规划前，应直接核对固定修订中的注册表与实现。
- 不要把该项目视为政府官方服务；新闻、司法、医疗、选举或其他决策用途应回查原始官方来源及其时效性。
- 启用 PII 数据集或大型本地数据集前，应审查未提供的 ACCEPTABLE_USE.md、SOURCES.md 和数据集指南，并确认 LGPD、数据许可、磁盘占用与保留策略。
- 当前证据没有展示依赖锁定、漏洞扫描、密钥日志脱敏或完整错误处理；部署前应单独审核这些控制。
- 批量执行、强制刷新和 Azure 数据集更新会发起大量请求并写入或替换缓存；应设置配额、监控和恢复措施。
这个 Agent 能做什么，适合哪些场景？
MCP Brasil 是一个用 Python 和 FastMCP 构建的自托管 MCP 服务器，将巴西经济、立法、司法、选举、医疗、教育、公共安全等 15 个主题领域的数据提供给 AI 客户端。项目公布了 70 项功能、533 个工具、131 个资源和 102 个提示，并通过 BM25 发现机制按上下文筛选工具。多数功能以异步 HTTP 方式调用外部 API，使用 httpx、Pydantic v2、速率限制和退避重试；部分大型数据集则下载到本机并由嵌入式 DuckDB 查询。根服务器还提供功能发现、工具推荐、跨 API 查询规划、并行批量执行和本地数据集枚举等元工具。它适合需要广泛巴西公共数据覆盖并愿意自行运行 MCP 服务的团队，但不是政府官方服务，且关键用途必须回到原始官方来源核验结果。
服务器通过 mcp_brasil.server 自动注册 data/、datasets/ 和 agentes/ 下的功能。REST 功能使用异步 HTTP 客户端读取巴西政府及相关公共数据 API，以 Pydantic 模型处理响应，并将结果作为 MCP tools、resources 和 prompts 暴露给客户端。recomendar_tools 配合 BM25 从 533 个工具中选择相关项，planejar_consulta 生成组合多个 API 的执行计划，executar_lote 在一次调用中并行发起查询。通过 MCP_BRASIL_DATASETS 启用的数据集会下载 CSV 或 ZIP 文件、写入本地 DuckDB 缓存，并通过预设查询工具提供数据；示例包括 TSE 候选人和投票、ANP 燃油价格、INEP 教育数据以及 ANAC 航空数据。服务器可通过 stdio 接入 Claude Desktop、Claude Code、VS Code 或 Cursor，也可通过 FastMCP 在 /mcp 提供 HTTP 服务。
- 研究巴西宏观经济的分析师，可联合查询 Banco Central 的 Selic、IPCA、汇率及 PIB 时间序列。
- 调查公共支出的记者，可检索联邦透明门户、政府合同、供应商及多个州审计法院的数据，但发布前应核对官方来源。
- 立法研究人员，可组合 Câmara 和 Senado 的议员、提案、投票、委员会及支出信息。
- 选举研究团队，可启用 TSE 本地数据集，分析 2014—2024 年候选人、申报资产、投票、社交链接和选举基金分配。
- 公共政策团队，可交叉引用 IBGE 与卫生、教育、治安或地方财政数据，比较州和市的指标。
- 开发 MCP 数据助手的工程师，可使用自动注册结构新增 API 功能，并以
make ci执行 lint、严格类型检查和测试。
这个 Agent 有哪些优点和局限？
- 覆盖 15 个主题领域和 70 项功能，并提供 533 个 MCP 工具，减少逐一集成巴西公共 API 的工作。
planejar_consulta和executar_lote分别支持跨来源查询规划及单次调用内的并行批量查询。- BM25 smart discovery 可按上下文缩小庞大工具集，避免客户端始终加载全部 533 个工具。
- 大型 TSE、INEP、ANP、ANAC 等数据集可使用本地 DuckDB 缓存，后续查询无需重复完整下载。
- 提供 stdio、HTTP、Claude Desktop、Claude Code、VS Code 和 Cursor 的明确启动方式，没有绑定单一模型提供商。
- 依赖大量外部政府及公共 API；项目明确警告这些接口可能文档不完整、参数覆盖有限或返回意外结果。
- 本地数据集约为 100 MB 至 1.6 GB，首次下载和导入可能耗时数分钟，并需要本地磁盘空间。
- 不同数据源拥有各自许可证，服务器使用还受 Acceptable Use Policy 约束；MIT 仅覆盖代码。
- 涉及健康、司法和选举等敏感数据时需要额外的法律与 LGPD 审查，部分含个人信息的数据集还受
MCP_BRASIL_LGPD_ALLOW_PII控制。 - README 中无密钥 API 数量以及功能、工具统计存在内部不一致，部署前需对所需功能和凭据进行实测。
如何安装或部署这个 Agent？
需要 Python，并使用 pip 或 uv 安装：
pip install mcp-brasil或：
uv add mcp-brasil使用 uvx 启动时无需在项目中预先安装：
uvx --from mcp-brasil python -m mcp_brasil.server可选凭据包括 TRANSPARENCIA_API_KEY、DATAJUD_API_KEY 和 META_ACCESS_TOKEN；brapi.dev 的部分查询还可使用免费 token。README 对无密钥 API 数量分别给出 66、62 和“其余 36 个”等不一致数字，因此采用前应按实际目标数据源验证凭据要求。
如何使用这个 Agent？
Claude Desktop：在 claude_desktop_config.json 的 mcpServers 中加入 mcp-brasil，命令设为 uvx，参数设为 ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"]，并在 env 中按需提供 API 密钥。
Claude Code：
claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.serverVS Code 或 Cursor：在项目根目录创建 .vscode/mcp.json，使用同一 uvx 命令和参数。
HTTP 客户端：
fastmcp run mcp_brasil.server:mcp --transport http --port 8000服务地址为 http://localhost:8000/mcp。连接后可用自然语言提出查询，例如比较过去 12 个月的 Selic 与 IPCA。大型本地数据集需先设置类似 MCP_BRASIL_DATASETS=tse_candidatos,tse_bens,tse_votacao；首次下载和导入可能持续数分钟。
这个 Agent 与同类方案有什么区别？
与为每个巴西公共数据源分别开发 API 集成相比，MCP Brasil 提供统一的 MCP 接口、自动注册、跨来源规划和批量执行。REST 直通功能适合轻量在线查询；可选 DuckDB 数据集则以更高的下载、存储和首次导入成本换取大型历史数据的本地查询能力。
常见问题
是否必须申请 API 密钥？
它是巴西政府的官方服务吗？
大型数据集会自动下载吗？
MCP_BRASIL_DATASETS 的数据集才会下载并导入本地 DuckDB；首次加载可能耗时数分钟。