New:Microsoft Teams Notifications Are Now Available in Socket.Learn more →

mcp-dados-br

Dependencies

Maintainers

Versions

Alerts

File Explorer

Advanced tools

License

Install Socket

Detect and block malicious and high-risk dependencies

Install

mcp-dados-br

Servidor MCP com dados públicos brasileiros: IBGE, Banco Central, INMET, Câmara dos Deputados e Senado Federal

PyPI

Version: 0.6.0

Weekly downloads: 167

Maintainers: 1

Created: last month

mcp-dados-br

English version

Servidor MCP (Model Context Protocol) que expõe dados públicos brasileiros como ferramentas para assistentes de IA: Claude Desktop, Claude Code, Cursor e qualquer cliente MCP.

Instalação

A forma mais simples, sem instalar nada permanentemente:

uvx mcp-dados-br

Configuração no Claude Desktop:

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

Ou no Claude Code:

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

A partir do código-fonte

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

Ferramentas disponíveis

Fonte	Tools	Descrição
IBGE/SIDRA	`ibge_populacao`, `ibge_pib`, `ibge_municipios`, `ibge_sidra`	População, PIB, busca de municípios e consulta genérica a qualquer agregado SIDRA
Banco Central	`bcb_serie`, `bcb_cambio`, `bcb_moedas`, `bcb_focus`	Séries SGS com atalhos nomeados (`selic`, `ipca`, `cdi`...), cotações PTAX, lista de moedas e expectativas do Boletim Focus
INMET	`inmet_estacoes`, `inmet_dados`	Lista de estações meteorológicas e dados horários observados (dados observacionais exigem token)
Câmara dos Deputados	`camara_deputados`, `camara_detalhes_deputado`, `camara_proposicoes`, `camara_votacoes_proposicao`, `camara_agenda`, `camara_tramitacao`	Deputados, proposições, votações, agenda e tramitações
Senado Federal	`senado_senadores`, `senado_materias`, `senado_votacoes`	Senadores em exercício, matérias legislativas e votações nominais com placar

Todas as fontes são APIs oficiais abertas — nenhuma chave de API necessária, exceto os dados horários do INMET (veja abaixo).

Configuração

Claude Desktop / Cursor

Adicione ao arquivo de configuração (claude_desktop_config.json ou 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

Token opcional do INMET

A listagem de estações (inmet_estacoes) é aberta. Já os dados horários observados (inmet_dados) exigem um token fornecido pelo INMET — solicite em portal.inmet.gov.br e configure a variável de ambiente no cliente MCP:

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

Sem o token, as demais 18 ferramentas funcionam normalmente.

Transporte streamable-http

Além do stdio padrão, o servidor pode rodar em modo HTTP remoto:

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

Aponte clientes para http://localhost:8000/mcp. Útil para Docker ou compartilhar o servidor na rede local. Por padrão o servidor escuta só em 127.0.0.1; defina MCP_HOST=0.0.0.0 para aceitar conexões de outras máquinas (a imagem Docker já faz isso).

Variável	Padrão	Função
`MCP_TRANSPORTE`	`stdio`	`streamable-http` liga o modo HTTP
`MCP_HOST`	`127.0.0.1`	Interface de escuta (`0.0.0.0` na imagem Docker)
`MCP_PORTA`	`8000`	Porta HTTP
`MCP_AUTH_TOKEN`	vazio	Se definido, exige `Authorization: Bearer <token>` em toda requisição

Autenticação (bearer opcional)

Risco: sem MCP_AUTH_TOKEN, o modo HTTP não tem autenticação. Escutando em 0.0.0.0 (como na imagem Docker), qualquer pessoa que alcance a porta pode chamar as 19 tools, consumir a sua cota nas APIs públicas e usar o seu INMET_TOKEN. O servidor registra um aviso no log quando sobe assim. Não publique a porta na internet sem token e prefira um proxy reverso com TLS na frente: sobre HTTP puro o token trafega em texto claro.

Gere um token longo e aleatório e passe-o ao servidor:

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

Requisições sem o cabeçalho, com outro esquema ou com token diferente recebem 401 com WWW-Authenticate: Bearer. A comparação usa secrets.compare_digest (tempo constante). No cliente, envie o cabeçalho, por exemplo no Claude Code:

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

Em stdio o token não se aplica: o processo só fala com o cliente que o iniciou.

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

Para uso só na própria máquina, publique a porta apenas no loopback: docker run -p 127.0.0.1:8000:8000 mcp-dados-br.

Exemplos de uso

Depois de configurar, pergunte diretamente ao assistente:

"Qual foi o IPCA dos últimos 6 meses?"
"O que o mercado espera para a Selic nas próximas reuniões?" (Boletim Focus)
"Quem são os deputados federais de Minas Gerais do partido X?"
"Qual a população de São Paulo em 2022? E o PIB?"
"Como está o dólar PTAX nos últimos dias?"
"Busque projetos de lei de 2025 sobre saúde mental"
"O que está na agenda da Câmara esta semana?"
"Como o Senado votou a PEC X? Qual o placar?"
"Quem são os senadores de Minas Gerais?"
"Quais estações automáticas do INMET existem no Amazonas?"

Desenvolvimento

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

Logs de depuração: configure MCP_LOG_LEVEL=DEBUG no cliente MCP. Para contribuir, leia o CONTRIBUTING.md.

Arquitetura

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
├── 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)

Dois transportes: stdio (padrão dos clientes desktop) e streamable-http (Docker/rede), este com autenticação bearer opcional via MCP_AUTH_TOKEN
Validação de entrada antes de montar qualquer URL: UF entre as 27 siglas, moeda ISO 4217 de 3 letras, datas ISO, códigos IBGE/SIDRA numéricos, IDs positivos e limites de dias/ultimas. Os limites também aparecem no inputSchema das tools, e o erro chega ao cliente MCP dizendo o que foi recebido e o que é aceito
Cache TTL de 10 minutos por requisição idêntica, com chave inequívoca (JSON ordenado de URL e parâmetros)
Retry automático em falhas de rede e em 429/502/503/504
Saídas formatadas como texto legível pelo modelo; bcb_serie, bcb_cambio e camara_deputados também devolvem structuredContent com outputSchema (datas ISO, valores numéricos), mantendo o texto como fallback
User-Agent com a versão instalada do pacote

Roadmap

v0.2 — INMET (estações + observacional com token) e Boletim Focus
v0.3 — Agenda da Câmara, transporte streamable-http e testes de integração agendados no CI
v0.4 — Tramitações, atalhos nomeados no SGS, imagem Docker
v0.5 — Publicação no PyPI (uvx mcp-dados-br), MCP Registry e Smithery
v0.6 — Validação de entrada, autenticação bearer no modo HTTP e saída estruturada
DOU: busca no Diário Oficial da União (aguardando API pública estável)
TSE: resultados eleitorais