需要让 AI 代理通过 MCP…

AI 客户端支持 MCP，并需要查询巴西公共 API（经济、立法、透明度、司法、选举、环境、健康等）时，安装 mcp-brasil 即可获得 213 个工具、55 个资源和 45 个提示。

适用场景

解决思路

1. 安装：运行 `pip install mcp-brasil`，或推荐运行 `uv add mcp-brasil`。
2. Claude Desktop 配置：在 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）中加入 `mcpServers.mcp-brasil`，设置 `command: uvx`、`args: ["--from","mcp-brasil","python","-m","mcp_brasil.server"]`，并在 `env` 中设置 `TRANSPARENCIA_API_KEY`、`DATAJUD_API_KEY`。
3. VS Code / Cursor 配置：在项目根目录创建 `.vscode/mcp.json`，写入 `servers.mcp-brasil`，设置 `command: uvx`、`args: ["--from","mcp-brasil","python","-m","mcp_brasil.server"]`，并在 `env` 中设置 `TRANSPARENCIA_API_KEY`、`DATAJUD_API_KEY`。
4. Claude Code CLI 配置：运行 `claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server`。
5. HTTP 传输配置：运行 `fastmcp run mcp_brasil.server:mcp --transport http --port 8000`，服务地址为 `http://localhost:8000/mcp`。
6. 环境变量配置：创建 `.env` 文件或在 shell 中 export；可选设置 `TRANSPARENCIA_API_KEY=your_key_here`（申请地址：https://portaldatransparencia.gov.br/api-de-dados/cadastrar-email）和 `DATAJUD_API_KEY=your_key_here`（申请地址：https://datajud-wiki.cnj.jus.br/api-publica/acesso）。
7. 调优环境变量：设置 `MCP_BRASIL_TOOL_SEARCH=bm25`（可选 `bm25 | code_mode | none`，默认 `bm25`）；设置 `MCP_BRASIL_HTTP_TIMEOUT=30.0`；设置 `MCP_BRASIL_HTTP_MAX_RETRIES=3`。
8. API 覆盖选择：按类别和 feature key 查询，包括 `ibge` 9 tools、`bacen` 9、`camara` 10、`senado` 26、`transparencia` 18、`tcu` 8、`tce_sp/rj/rs/sc/pe/ce/rn/pi/to` 共 39、`datajud` 7、`jurisprudencia` 6、`tse` 15、`inpe` 4、`ana` 3、`saude` 4、`tabua_mares` 7、`pncp` 6、`dadosabertos` 8、`brasilapi` 16、`dados_abertos` 4、`diario_oficial` 4、`transferegov` 5、`redator` 5；26 个 API 无需 key，仅 2 个需要免费注册。
9. 根服务器 Meta-Tools：使用 `listar_features` 列出全部 28 个 features；使用 `recomendar_tools` 做 BM25 搜索，获取与查询相关的 tools；使用 `planejar_consulta` 为复杂查询构建多 API 执行计划；使用 `executar_lote` 在一次请求中并行运行多个 tool calls。
10. 开发环境准备：运行 `git clone https://github.com/jxnxts/mcp-brasil.git`，然后运行 `cd mcp-brasil`。
11. 开发命令：运行 `make dev` 安装全部依赖（prod + dev）；`make test` 运行所有测试；`make test-feature F=ibge` 测试单个 feature；`make lint` 做 lint + format check；`make ruff` 自动修复 lint + format；`make types` 运行 mypy strict mode；`make ci` 运行 lint + types + test 完整 CI；`make run` 启动服务（stdio transport）；`make serve` 启动服务（HTTP :8000）；`make inspect` 列出所有 tools/resources/prompts。
12. 架构：按 feature 分包；`server.py` 自动发现 features，不要手动编辑；`_shared/` 放共享 HTTP client、rate limiting、BM25；`data/` 放 27 个 API features；`agentes/` 放智能 agent features，如 `redator`；每个 feature 包含 `__init__.py`（导出 `FEATURE_META`）、`server.py`（导出 `mcp: FastMCP`）、`tools.py`、`client.py`、`schemas.py`、`constants.py`。
13. 自动注册：根 `server.py` 扫描 `__init__.py` 中的 `FEATURE_META` 和 `server.py` 中的 `mcp: FastMCP`，无需手动注册。
14. 添加新 feature：运行 `mkdir src/mcp_brasil/data/myfeature`，并创建 `__init__.py,server.py,tools.py,client.py,schemas.py,constants.py`。
15. `__init__.py` 写法：导入 `FeatureMeta`，定义 `FEATURE_META = FeatureMeta(name="myfeature", description="Short description of the API", tags=["category"], requires_key=False)`。
16. `server.py` 写法：导入 `FastMCP` 和 `register_tools`，定义 `mcp = FastMCP("myfeature")`，调用 `register_tools(mcp)`。
17. `client.py` 写法：使用 `httpx` 和 `mcp_brasil._shared.http.get_client`；定义 `BASE_URL`；在 async 函数中用 `async with get_client() as client` 发 GET，调用 `response.raise_for_status()`，返回 `response.json()`。
18. `schemas.py` 写法：使用 Pydantic v2 的 `BaseModel`、`Field`、`Optional` 定义响应模型。
19. `tools.py` 写法：在 `register_tools(mcp)` 内用 `@mcp.tool(description="...")` 注册 `async def`，调用 client，返回 Pydantic 模型列表。
20. 测试写法：在 `tests/data/myfeature/test_tools.py` 中用 `pytest`、`AsyncMock`、`patch` mock client 的 `fetch_data`，构造 `FastMCP("test-myfeature")`，调用 `register_tools`，断言结果。
21. Pattern 1：用 `planejar_consulta` 做跨 API 规划；例如让 agent 执行 `Crie um plano de consulta para analisar o deputado federal João Silva: gastos, votações, proposições e financiamento de campanha.`，返回结合 `camara`、`tse`、`transparencia` 的结构化执行计划。
22. Pattern 2：用 `executar_lote` 并行执行；例如让 agent 执行 `Execute em paralelo: taxa Selic atual, IPCA dos últimos 12 meses, e câmbio USD/BRL de hoje.`，并发触发三个 `bacen` tool calls。
23. Pattern 3：用 `recomendar_tools` 智能发现；例如让 agent 执行 `Quais tools devo usar para investigar contratos suspeitos em licitações municipais?`，BM25 从 213 tools 中过滤出相关工具，如 `tce_sp`、`pncp`、`tcu`、`transparencia`。
24. Pattern 4：在代码中直接调用 tool；导入 `asyncio`、`buscar_serie_temporal`、`buscar_municipios`；运行 `await buscar_serie_temporal(codigo="432", ultimos=12)` 获取 Selic；运行 `await buscar_municipios(uf="SP")` 获取圣保罗州城市；用 `asyncio.run(main())` 执行。
25. Pattern 5：用 `brasilapi` 查询 CNPJ/CEP；导入 `consultar_cnpj`、`consultar_cep`；运行 `await consultar_cnpj(cnpj="00000000000191")`；运行 `await consultar_cep(cep="01310100")`。
26. 自然语言查询示例：经济分析可问 `Qual a tendência da taxa Selic nos últimos 12 meses? Compare com IPCA.`。
27. 自然语言查询示例：立法研究可问 `Quais projetos de lei sobre IA tramitaram na Câmara em 2024? Quem foram os autores?`。
28. 自然语言查询示例：透明度/反腐可问 `Quais os 10 maiores contratos do governo federal em 2024?`。
29. 自然语言查询示例：跨州比较可问 `Compare gastos per capita com saúde em SP e MG cruzando TCE-SP e IBGE.`。
30. 自然语言查询示例：司法可问 `Busque processos sobre licitação irregular no TCU. Quais as penalidades?`。
31. 自然语言查询示例：竞选财务可问 `Quais os maiores doadores da campanha do candidato X?`。
32. 自然语言查询示例：环境可问 `Quantos focos de queimada foram registrados no Cerrado em agosto 2024?`。
33. 自然语言查询示例：文档生成（redator feature）可问 `Redija um ofício solicitando informações sobre o contrato 001/2024 com dados reais do Portal da Transparência.`。
34. 故障排查：服务未启动时，运行 `python -m mcp_brasil.server --help` 验证安装；运行 `uvx --from mcp-brasil python -c "import mcp_brasil; print(mcp_brasil.__version__)"` 检查 uvx 能否找到包。
35. 故障排查：API 返回 401/403 时，`transparencia` 和 `datajud` 无 key 会静默降级；设置 `TRANSPARENCIA_API_KEY` 和 `DATAJUD_API_KEY` 获得完整访问；key 免费，申请地址为 https://portaldatransparencia.gov.br/api-de-dados/cadastrar-email 和 https://datajud-wiki.cnj.jus.br/api-publica/acesso。
36. 故障排查：可见工具过多导致上下文溢出时，设置 `MCP_BRASIL_TOOL_SEARCH=bm25`（默认）只暴露与当前查询相关的工具；`code_mode` 暴露所有工具；`none` 禁用过滤。
37. 故障排查：慢速政府 API 超时时，设置 `MCP_BRASIL_HTTP_TIMEOUT=60.0` 增加超时；设置 `MCP_BRASIL_HTTP_MAX_RETRIES=5` 增加重试。
38. 故障排查：Feature 未自动发现时，确保 feature 文件夹同时导出 `FEATURE_META`（`__init__.py`）和 `mcp: FastMCP`（`server.py`）；运行 `make inspect` 验证 feature 出现在工具列表。
39. 测试特定 feature：运行 `make test-feature F=bacen`；运行 `make test-feature F=transparencia`。
40. 设计原则：所有地方 async；使用 `httpx` async client，所有 tools 为 `async def`。
41. 设计原则：所有 API 响应用 Pydantic v2 typed schemas 校验。
42. 设计原则：`_shared/http.py` 内置 rate limiting with backoff，对 feature code 透明。
43. 设计原则：零手动注册；新增文件夹自动发现。
44. 设计原则：BM25 smart filtering 防止 213 tools 撑爆上下文窗口。
45. 设计原则：Graceful degradation；需要 key 的 API 无 key 也能用（受限）。

适用边界 · 注意事项

• 当目标数据不是巴西公共数据，或 AI 客户端不支持 MCP 时。
• 当无法安装/运行 Python、uv/uvx、fastmcp，或无法配置 MCP 客户端时。
• 当需要生产级 SLA、稳定低延迟或完全避免免费 API key 注册时。