mcp-brasil实战教程：一句自然语言，快速查遍巴西利率、政府合同与选举数据

mcp-brasil是一个开源的MCP 服务器，让你用一句自然语言，就能查遍巴西 70 个公共数据源——央行利率（Selic）、通胀（IPCA）、政府合同、选举结果、司法案件等。它内置533 个查询工具，其中 66 个数据源无需 API 密钥，安装后开箱即用。本教程面向零基础用户，5 分钟即可完成 mcp-brasil 安装与配置。

1️⃣ 什么是 mcp-brasil：给 AI 助手装上"巴西数据大脑"

如果你用过 AI 助手（Claude、GPT、Copilot 等），可能发现它们回答巴西政府数据时常常"一本正经地瞎编"。问题在于：AI 模型本身不直连实时数据。

MCP（Model Context Protocol）就是解决这个问题的标准协议——它像一个"数据插头"，把 AI 助手直接连到权威数据源。mcp-brasil 做的事，就是把巴西 70 个官方数据源一次性插好：

✅对新手最友好的一点：你不需要会写代码，只需要会"提问"。

完整数据源清单见 docs/reference/features.md 与 SOURCES.md。

2️⃣ 一键安装步骤：2 分钟配好 mcp-brasil

第一步：安装

打开终端，任选一条命令即可：

pip install mcp-brasil

第二步：配置你的 AI 客户端

Claude Desktop：在claude_desktop_config.json中加入：

{ "mcpServers": { "mcp-brasil": { "command": "uvx", "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"] } } }

VS Code / Cursor：在项目根目录创建.vscode/mcp.json，写入同样的配置即可。

Claude Code：一行命令搞定——

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

💡 4 个数据源（透明度门户、DataJud、Meta 广告库、B3）支持可选 API 密钥，不加密钥也完全能跑，只是请求频率上限更低。详细配置见 docs/guide/quickstart.md 和 docs/reference/configuration.md。

3️⃣ 场景一：一句话查巴西利率与通胀走势

连上服务器后，直接对 AI 说：

"最近 12 个月 Selic 基准利率的走势如何？请和同期通胀率（IPCA）做个对比。"

AI 会自动调用巴西央行工具（如bacen_consultar_serie，其中 Selic 系列代码 432、IPCA 为 433，还支持bacen_indicadores_atuais一次并行拉取 5 项核心指标），几秒钟后你拿到的就是一张带日期和数值的对照表。

整个请求的旅程是这样的：

巴西央行相关工具源码在 src/mcp_brasil/data/bacen/，你可以自己翻一翻每个工具能做什么。

4️⃣ 场景二：政府合同与支出透明度查询

想知道政府钱花在哪了？试试这些问法：

• "2024 年联邦政府 10 笔最大合同是什么？供应商分别是谁？"
• "查一下某个 CNPJ 企业在透明度门户下的合同记录。"
• "某市 2024 年公共卫生领域的支出是多少？"

背后对应的是 54 个transparencia工具（如transparencia_buscar_contratos、transparencia_consultar_despesas、transparencia_detalhar_contrato），覆盖合同、支出、公务员、旅行、财政放弃等——源码位于 src/mcp_brasil/data/transparencia/。

还可以跨州对比："对比圣保罗州和米纳斯吉拉斯州的人均医疗支出"，AI 会自动组合 TCE 州审计法院和 IBGE 人口数据来完成。

5️⃣ 场景三：选举数据与候选人查询

选举研究是 mcp-brasil 的重头戏，TSE（巴西最高法院选举机构）模块提供 15 个工具：

• "列出 2024 年圣保罗州的候选人。" →tse_listar_candidatos
• "查一下某候选人的竞选财务报告。" →tse_consultar_prestacao_contas
• "2022 大选各州结果如何？" →tse_resultado_por_estado

🚀进阶玩法：2014–2024 的完整选举大数据（约 400 万条候选人记录、候选人资产、逐市投票结果）支持本地数据集模式——首次运行自动下载约百 MB 数据到本地，用嵌入式 DuckDB 跑 SQL，之后查询只要几毫秒。只需在环境变量中开启：

MCP_BRASIL_DATASETS=tse_candidatos,tse_bens,tse_votacao

完整数据集指南见 docs/guide/datasets.md。

6️⃣ 进阶：4 个"元工具"，让 AI 自己规划复杂查询

面对 533 个工具，AI 会不会"选择困难"？mcp-brasil 内置了智能发现机制（默认 BM25 过滤，只呈现最相关的 10 个工具），外加 4 个元工具（源码入口 src/mcp_brasil/server.py）：

典型组合流程：先用planejar_consulta生成计划 → 再用executar_lote并行执行 → 最后由 AI 汇总。详细说明见 docs/reference/smart-tools.md。

7️⃣ 想贡献新数据源？一个文件夹就够了

mcp-brasil 采用"按特性分包 + 自动注册"架构：新增一个数据源不需要修改任何注册代码，只需按约定新建一个文件夹（server.py、tools.py、client.py、schemas.py、constants.py），根服务器启动时会自动发现并挂载。

架构详解见 docs/concepts/architecture.md，贡献指南见 docs/guide/adding-features.md。

8️⃣ 常见问题 FAQ

问：必须申请 API 密钥吗？不用。70 个数据源中 66 个免密钥直接可用；可选密钥只用来提升请求频率上限。

问：可以用中文提问吗？可以。提示词用中文、葡语或英文都可以，AI 客户端会自行选择正确的工具。

问：数据可以商用/发报告吗？注意：mcp-brasil 是独立社区项目，不是巴西官方服务；每个数据源有各自许可证，且 AI 模型可能产生幻觉。用于商业、新闻或决策前，请务必阅读 SOURCES.md、ACCEPTABLE_USE.md 并回到官方数据源核实。

总结：从"提问"到"拿到数据"只要三步

1. 装：pip install mcp-brasil
2. 配：把 mcp-brasil 加入你 AI 客户端的 MCP 配置
3. 问：用自然语言查利率、合同、选举……剩下交给 533 个工具

项目完整文档入口在 README.md，快速上手指南在 docs/guide/quickstart.md。现在就去试试："最近 12 个月 Selic 的走势，对比一下 IPCA 通胀"——看看你的 AI 助手几秒内能交出什么样的答案。🇧🇷