mcp-brasil
mcp-dados-br
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-brConfiguraçã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-brA partir do código-fonte
git clone https://github.com/lucianoon/mcp-dados-br
cd mcp-dados-br
uv syncRelated MCP server: ibge-data-mcp
Ferramentas disponíveis
Fonte | Tools | Descrição |
IBGE/SIDRA |
| População, PIB, busca de municípios e consulta genérica a qualquer agregado SIDRA |
Banco Central |
| Séries SGS com atalhos nomeados ( |
INMET |
| Lista de estações meteorológicas e dados horários observados (dados observacionais exigem token) |
Câmara dos Deputados |
| Deputados, proposições, votações, agenda e tramitações |
Senado Federal |
| 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-brToken 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-brAponte 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 |
|
|
|
|
| Interface de escuta ( |
|
| Porta HTTP |
| vazio | Se definido, exige |
Autenticação (bearer opcional)
Risco: sem
MCP_AUTH_TOKEN, o modo HTTP não tem autenticação. Escutando em0.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 seuINMET_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-brRequisiçõ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-brPara 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 srcLogs 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_TOKENValidaçã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 noinputSchemadas tools, e o erro chega ao cliente MCP dizendo o que foi recebido e o que é aceitoCache 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/504Mudanç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' ausenteSaídas formatadas como texto legível pelo modelo;
bcb_serie,bcb_cambioecamara_deputadostambém devolvemstructuredContentcomoutputSchema(datas ISO, valores numéricos), mantendo o texto como fallbackUser-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 Smitheryv0.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 toolsbcb_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
Brazilian public data API for AI agents. BCB, IBGE, CVM, B3, compliance. x402 payments on Base.
Banco Central do Brasil (BCB): SGS series, Focus expectations, PTAX, stats + provenance. 17 tools.
Brazil CNPJ, CEP, Selic/IPCA/PTAX, holidays, banks/ISPB for agents. Pay per call in USDC (x402).
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceConnects 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
- FlicenseNot gradedqualityDmaintenanceEnables LLMs to access Brazilian IBGE statistical data (population, economy, agriculture) via natural language, with tools for querying aggregated data and metadata.-
- AlicenseAqualityDmaintenanceEnables AI agents to access Brazilian statistical, geographic, and economic data in real-time via IBGE public APIs.3214 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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