MCP Dados Brasil

mcp-dados-br

English version

MCP（Model Context Protocol）服务，将巴西公共数据作为工具提供给 AI 助手使用：Claude Desktop、Claude Code、Cursor 及任何 MCP 客户端。

安装

最简单的方式，无需永久安装任何内容：

uvx mcp-dados-br

在 Claude Desktop 中配置：

{
  "mcpServers": {
    "dados-brasil": {
      "command": "uvx",
      "args": ["mcp-dados-br"]
    }
  }
}

或在 Claude Code 中：

claude mcp add dados-brasil -- uvx mcp-dados-br

从源代码安装

git clone https://github.com/lucianoon/mcp-dados-br
cd mcp-dados-br
uv sync

可用工具

来源	工具	描述
IBGE/SIDRA	ibge_populacao, ibge_pib, ibge_municipios, ibge_sidra	人口、GDP、市镇查询，以及对任意 SIDRA 汇总数据的通用查询
巴西中央银行	bcb_serie, bcb_cambio, bcb_moedas, bcb_focus	SGS 系列数据及命名快捷方式（selic、ipca、cdi 等）、PTAX 汇率、货币列表和《Focus 公报》预期
INMET	inmet_estacoes, inmet_dados	气象站列表和观测小时数据（观测数据需要令牌）
众议院	camara_deputados, camara_detalhes_deputado, camara_proposicoes, camara_votacoes_proposicao, camara_agenda, camara_tramitacao	众议员、提案、投票、议程和审议进程
联邦参议院	senado_senadores, senado_materias, senado_votacoes	在任参议员、立法议案和带有票数统计的唱名投票

所有数据源均为官方开放 API——无需 API 密钥， INMET 小时数据除外（见下文）。

配置

Claude Desktop / Cursor

添加到配置文件（claude_desktop_config.json 或 mcp.json）：

{
  "mcpServers": {
    "mcp-dados-br": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/mcp-dados-br", "mcp-dados-br"]
    }
  }
}

Claude Code

claude mcp add mcp-dados-br -- uv run --directory /caminho/para/mcp-dados-br mcp-dados-br

可选的 INMET 令牌

站点列表（inmet_estacoes）是开放的。而观测小时数据 （inmet_dados）则需要 INMET 提供的令牌——请在 portal.inmet.gov.br 申请，并在 MCP 客户端中配置 环境变量：

{
  "mcpServers": {
    "mcp-dados-br": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/mcp-dados-br", "mcp-dados-br"],
      "env": { "INMET_TOKEN": "seu-token" }
    }
  }
}

没有令牌时，其余 18 个工具仍可正常使用。

streamable-http 传输

除了标准的 stdio 外，服务还可以在远程 HTTP 模式下运行：

MCP_TRANSPORTE=streamable-http MCP_PORTA=8000 mcp-dados-br

将客户端指向 http://localhost:8000/mcp。适用于 Docker 或在本地网络中 共享服务。默认情况下，服务只监听 127.0.0.1；设置 MCP_HOST=0.0.0.0 即可接受来自其他机器的连接 （Docker 镜像已设置此项）。

变量	默认值	作用
MCP_TRANSPORTE	stdio	streamable-http 用于启用 HTTP 模式
MCP_HOST	127.0.0.1	监听接口（Docker 镜像中为 0.0.0.0）
MCP_PORTA	8000	HTTP 端口
MCP_AUTH_TOKEN	空	若已设置，每个请求都必须携带 Authorization: Bearer <token>

认证（可选 bearer）

**风险：**如果没有 MCP_AUTH_TOKEN，HTTP 模式就没有身份验证。监听 在 0.0.0.0（如 Docker 镜像中的设置）时，任何能访问该端口的人都可以 调用 19 个工具、消耗你在公共 API 上的配额，并使用你的 INMET_TOKEN。服务器在以这种方式启动时会在日志中记录警告。请勿在没有令牌的情况下 将端口暴露到互联网，并优先在前面使用带 TLS 的反向代理：在纯 HTTP 上，令牌会以明文传输。

生成一个长且随机的令牌，并传给服务器：

export MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
MCP_TRANSPORTE=streamable-http mcp-dados-br

未携带请求头、使用其他方案或令牌不匹配的请求会收到 401，并带有 WWW-Authenticate: Bearer。比较使用 secrets.compare_digest （恒定时间）。在客户端中发送请求头，例如在 Claude Code 中：

claude mcp add --transport http dados-brasil http://localhost:8000/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

stdio 模式不适用令牌：进程只会与启动它的客户端通信。

Docker

docker build -t mcp-dados-br .
docker run -p 8000:8000 \
  -e MCP_AUTH_TOKEN="$MCP_AUTH_TOKEN" \
  -e INMET_TOKEN=seu-token \
  mcp-dados-br

若仅在本机使用，请只在 loopback 上发布端口： docker run -p 127.0.0.1:8000:8000 mcp-dados-br。

使用示例

配置完成后，直接向助手提问：

• “过去 6 个月的 IPCA 是多少？”
• “市场对未来几次会议的 Selic 有何预期？”（Boletim Focus）
• “X 党来自米纳斯吉拉斯州的联邦众议员有哪些？”
• “圣保罗 2022 年的人口是多少？GDP 呢？”
• “最近几天的美元 PTAX 汇率如何？”
• “搜索 2025 年有关心理健康的法案”
• “本周众议院的议程有哪些？”
• “参议院如何对 PEC X 投票？票数如何？”
• “米纳斯吉拉斯州的参议员有哪些？”
• “亚马逊州有哪些 INMET 自动气象站？”

开发

uv sync --dev
uv run pytest              # suíte unitária (mocks)
uv run pytest -m integration   # consulta as APIs reais
uv run ruff check .
uv run mypy src

调试日志：在 MCP 客户端中设置 MCP_LOG_LEVEL=DEBUG。 如需贡献，请阅读 CONTRIBUTING.md。

架构

src/mcp_dados_br/
├── server.py        # Servidor MCP, registro das tools e escolha do transporte
├── auth.py          # Middleware ASGI de autenticação bearer (modo HTTP)
├── validacao.py     # Validação dos argumentos das tools (UF, moeda, datas, limites)
├── saida.py         # Resultado com texto + structuredContent
├── http.py          # Cliente HTTP compartilhado, retry e tratamento de erros
├── payload.py       # Leitura defensiva das respostas das APIs (fonte e campo no erro)
├── cache.py         # Cache TTL em memória para as respostas das APIs
└── tools/
    ├── ibge.py      # SIDRA v3 + localidades v1
    ├── bcb.py       # SGS + Olinda (PTAX e Boletim Focus)
    ├── inmet.py     # Estações e dados observacionais
    ├── camara.py    # Dados Abertos da Câmara v2
    └── senado.py    # Dados Abertos do Senado (LegisSaber)

• 两种传输方式：stdio（桌面客户端的默认方式）和 streamable-http （Docker/网络）；后者可通过 MCP_AUTH_TOKEN 选择性启用 bearer 身份验证
• 在构造任何 URL 之前验证输入：UF 限定为 27 个州缩写， 货币为 3 个字母的 ISO 4217 代码，日期为 ISO 格式，IBGE/SIDRA 代码为数字，ID 必须为正数，且 dias/ultimas 必须在限制范围内。限制也会显示在 工具的 inputSchema 中，错误会告知 MCP 客户端收到的内容和可接受的值
• 对完全相同的请求使用 10 分钟 TTL 缓存，缓存键明确无歧义（URL 和参数的 排序 JSON）
• 网络故障以及 429/502/503/504 错误时自动重试
• 上游 API 格式发生变化（字段重命名、类型更改）时，工具会返回错误（isError: true），并指出来源和字段，例如： Resposta inesperada de BCB/PTAX: campo 'cotacaoCompra' ausente
• 输出格式为模型易读的文本；bcb_serie、bcb_cambio 和 camara_deputados 还会返回带有 outputSchema 的 structuredContent （ISO 日期、数值），同时保留文本作为后备
• User-Agent 包含已安装的软件包版本

路线图

• v0.2 — INMET（气象站 + 使用令牌获取观测数据）和 Boletim Focus
• v0.3 — 众议院议程、streamable-http 传输方式，以及在 CI 中安排集成测试
• v0.4 — 议案流程、SGS 中的命名快捷方式、Docker 镜像
• v0.5 — 发布到 PyPI（uvx mcp-dados-br）、MCP Registry 和 Smithery
• v0.6 — 输入验证、HTTP 模式下的 bearer 身份验证和结构化输出
• DOU：搜索《联邦官方公报》（等待稳定的公共 API）
• TSE：选举结果

许可证

MIT