Skip to main content
Glama
mcp-brasil

mcp-brasil

by lucianoon

mcp-dados-br

CI Integração PyPI Python Licença: MIT

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

Related MCP server: ibge-data-mcp

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

  • Mudança de formato numa API upstream (campo renomeado, tipo trocado) vira erro da tool (isError: true) com a fonte e o campo, ex.: Resposta inesperada de BCB/PTAX: campo 'cotacaoCompra' ausente

  • 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

Licença

MIT

Available Tools

14 tools
bcb_cambioA

Cotações de câmbio PTAX do Banco Central para uma moeda nos últimos N dias.

Args: moeda: Símbolo da moeda (ex.: "USD", "EUR", "GBP"). Use a tool bcb_moedas para listar as moedas disponíveis. dias: Quantidade de dias úteis de cotação a retornar (padrão 7).

Inputs: dias, moeda. Returns: result

bcb_focusB

Expectativas de mercado do Boletim Focus (Boletim Focus) do Banco Central.

Mostra a projeção média dos analistas de mercado para os próximos períodos.

Args: indicador: Um de: "selic", "ipca", "pib" ou "cambio".

Inputs: indicador. Returns: result

bcb_moedasA

Lista as moedas com cotação PTAX disponíveis no Banco Central.

Inputs: no named parameters. Returns: result

bcb_serieA

Consulta séries temporais do Sistema Gerenciador de Séries (SGS) do Banco Central.

Args: codigo: Código da série SGS. Exemplos: 1178 (Selic meta), 433 (IPCA mensal), 13522 (IPCA acumulado em 12 meses), 4390 (CDI), 36 (salário mínimo), 189 (IGP-M), 206 (INPC). Catálogo: https://www3.bcb.gov.br/sgspub/ data_inicial: Data inicial ISO "AAAA-MM-DD". Padrão: últimos 90 dias. data_final: Data final ISO "AAAA-MM-DD". Padrão: hoje.

Inputs: codigo (required), data_final, data_inicial. Returns: result

camara_deputadosA

Lista deputados federais da Câmara com filtros opcionais.

Args: uf: Sigla da unidade federativa, ex.: "SP", "MG". partido: Sigla do partido, ex.: "PT", "PSDB". nome: Nome (total ou parcial) do parlamentar. legislatura: Número da legislatura (ex.: 57 para a atual). Padrão: atual.

Inputs: uf, nome, partido, legislatura. Returns: result

camara_detalhes_deputadoA

Detalhes de um deputado federal pelo ID: nome civil, partido, UF e gabinete.

Args: id_deputado: ID numérico do deputado (obtido via camara_deputados).

Inputs: id_deputado (required). Returns: result

camara_proposicoesB

Busca proposições legislativas na Câmara (projetos de lei, emendas etc.).

Args: ano: Ano de apresentação, ex.: 2025. palavras_chave: Palavras-chave na ementa, ex.: "saude mental". sigla_tipo: Sigla do tipo, ex.: "PL", "PEC", "MPV".

Inputs: ano, sigla_tipo, palavras_chave. Returns: result

camara_votacoes_proposicaoA

Lista as votações realizadas para uma proposição específica da Câmara.

Args: id_proposicao: ID numérico da proposição (obtido via camara_proposicoes).

Inputs: id_proposicao (required). Returns: result

ibge_municipiosA

Busca municípios brasileiros pelo nome (IBGE), com filtro opcional por UF.

Args: nome: Nome (total ou parcial) do município, ex.: "campinas". uf: Sigla opcional da UF para restringir a busca, ex.: "SP".

Inputs: nome (required), uf. Returns: result

ibge_pibA

PIB a preços correntes de uma unidade da federação ou do Brasil (IBGE/SIDRA).

Args: uf: Sigla da UF (ex.: "MG", "BA") ou "BR" para o total nacional. ano: Ano de referência. Se omitido, retorna o período mais recente disponível.

Inputs: uf, ano. Returns: result

ibge_populacaoA

População residente de uma unidade da federação ou do Brasil (IBGE/SIDRA).

Args: uf: Sigla da UF (ex.: "SP", "RJ") ou "BR" para o total nacional. ano: Ano de referência. Se omitido, retorna o período mais recente disponível.

Inputs: uf, ano. Returns: result

ibge_sidraA

Consulta genérica à API SIDRA do IBGE para qualquer indicador.

Args: agregado: ID do agregado SIDRA (ex.: "4709" população, "5938" PIB, "1737" inflação INPC). Consulte https://servicodados.ibge.gov.br/api/v3/agregados para a lista completa. variavel: ID da variável dentro do agregado (ex.: "93"). localidades: Filtro de localidades no formato SIDRA, ex.: "N1[1]" Brasil, "N3[35]" São Paulo (estado), "N6[3550308]" Campinas (município). periodos: Períodos, ex.: "-1" (último), "2022", "2020/2024".

Inputs: agregado (required), variavel (required), periodos, localidades. Returns: result

inmet_dadosA

Dados horários observados de uma estação automática do INMET (últimos dias).

Requer o ambiente INMET_TOKEN com token fornecido pelo INMET (solicite em https://portal.inmet.gov.br). Sem token, use inmet_estacoes.

Args: estacao: Código da estação, ex.: "A001". Liste códigos com inmet_estacoes. dias: Quantidade de dias retroativos a consultar (padrão 2, máximo 7).

Inputs: estacao (required), dias. Returns: result

inmet_estacoesA

Lista estações meteorológicas do INMET (não requer autenticação).

Args: tipo: "T" para estações automáticas ou "M" para convencionais. uf: Sigla opcional da UF para filtrar, ex.: "SP".

Inputs: uf, tipo. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (e.g., population vs PIB vs municipalities vs generic SIDRA), and within each source (IBGE, BCB, INMET, Camara) the functions are clearly separated—list vs details vs votes. There is no meaningful overlap that would cause an agent to misselect.

    Naming Consistency5/5

    All tools follow a consistent 'source_noun' pattern with snake_case (ibge_populacao, bcb_serie, inmet_estacoes, camara_deputados). The only slight variation is the use of singular vs plural nouns, but this is a natural linguistic choice and does not break the overall consistency.

    Tool Count5/5

    With 14 tools, the server is well-scoped for its purpose of aggregating Brazilian public data across four distinct domains. No tool feels redundant, and the count is within the optimal 3–15 range, striking a good balance between breadth and focus.

    Completeness4/5

    Each domain is reasonably covered: IBGE has core indicators plus generic SIDRA, BCB has time series, exchange rates, currency list, and market focus, INMET has stations and data (with token gate), and Camara offers deputies, details, propositions, and votes. Minor gaps exist (e.g., no Camara session coverage, no direct inflation series), but the generic SIDRA tool compensates for many potential lacks, and the core workflows are achievable.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects AI agents to 28 Brazilian public APIs, providing over 200 tools to access data on economy, legislation, transparency, and the judiciary. It enables complex queries and cross-referencing of government datasets like IBGE, the Central Bank, and the National Congress through natural language.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to query 153 live Brazilian government data tools across federal and state sources, including economy, legislature, judiciary, elections, health, education, and more, reading directly from original APIs.
      MIT