CensoSenso MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CensoSenso MCP Compare a população de São Paulo e Rio de Janeiro no Censo 2022"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CensoSenso MCP
Servidor MCP independente para consulta, comparação e análise de dados oficiais do IBGE, com 24 ferramentas, procedência reproduzível, validação de contratos e transporte remoto via Cloudflare Workers.
Endpoint MCP remoto: https://censosenso.poderdapalavra.org/mcp
Protótipo público 1. A versão 0.7.0 é experimental, somente leitura e disponibilizada sem SLA. O canal oficial inicial é o endpoint remoto acima. O pacote npm ainda não integra este lançamento.
O CensoSenso MCP é uma implementação de Model Context Protocol voltada ao uso analítico de dados públicos brasileiros. A superfície atual reúne ferramentas de localidades, Censo Demográfico, SIDRA, indicadores, Cidades@, saúde, saneamento, economia, classificações, malhas administrativas, vizinhança municipal, recortes territoriais, notícias e calendário.
O princípio central é simples: uma resposta útil não deve trazer apenas um número. Sempre que o contrato da ferramenta permitir, o resultado preserva fonte, URL reproduzível, período ou vintage, instante de extração, indicação de derivação e atributos de qualidade.
Sumário
Related MCP server: ibge-data-mcp
Política de versionamento
A sequência pública usa versões pré-1.0: 0.x.0 para acréscimo funcional e 0.x.y para correções ou melhorias de funcionalidades existentes. A família 0.9.x é reservada ao beta e 1.0.0 ao primeiro lançamento estável. Consulte docs/VERSIONAMENTO.md.
Versão e estado
versão do servidor: 0.7.0;
linguagem principal: TypeScript;
runtime: Node.js 22+;
protocolo: Model Context Protocol;
transporte local: STDIO;
transporte remoto: Streamable HTTP;
hospedagem remota: Cloudflare Workers;
endpoint:
https://censosenso.poderdapalavra.org/mcp;health:
https://censosenso.poderdapalavra.org/health;status:
https://censosenso.poderdapalavra.org/status;licença do software: MIT;
fonte principal dos dados: IBGE;
natureza deste lançamento: protótipo público experimental, sem SLA.
A superfície atual possui 24 ferramentas: 22 componentes ibge_* e duas ferramentas genéricas de pesquisa assistida, search e fetch.
Documentação técnica
O deploy remoto foi homologado com a sequência MCP real:
initialize;emissão/captura de
mcp-session-id;notifications/initialized;tools/list;tools/call;consulta efetiva a fonte oficial;
retorno estruturado com procedência.
Validação dos 645 municípios paulistas
A evidência completa desta execução está em docs/VALIDACAO_SP_645.md. O resultado municipal público pode ser consultado em validation/sp/0.6.0/municipios-sp-645.csv.
A versão 0.6.0 possui um gate reproduzível específico para o universo municipal do Estado de São Paulo.
Execução validada em 5 de outubro de 2026:
Métrica | Resultado |
Municípios retornados pela API oficial | 645 |
Validação estrutural | aprovada |
Divergências globais | 0 |
Divergências municipais | 0 |
Amostra determinística de chamadas reais | 21 |
Amostra aprovada | 21/21 |
Falhas na amostra | 0 |
SHA-256 do snapshot validado |
|
O gate consulta:
https://servicodados.ibge.gov.br/api/v1/localidades/estados/35/municipios?orderBy=nomeO que é verificado nos 645 registros
Para cada município:
código IBGE com exatamente 7 dígitos;
prefixo
35, correspondente ao Estado de São Paulo;unicidade dos códigos;
nome não vazio;
unicidade dos nomes normalizados em pt-BR;
código da UF igual a 35, quando informado pela origem;
sigla da UF igual a SP, quando informada;
região igual a Sudeste, quando informada.
No conjunto:
total obrigatório de 645 registros;
inexistência de códigos duplicados;
inexistência de qualquer registro marcado como divergente.
Como a amostra de 21 municípios é construída
Além da validação estrutural 645/645, o gate cria uma amostra determinística para chamar as ferramentas reais do servidor.
A amostra começa por:
município de São Paulo;
Guararema;
primeiro e último código na ordenação;
primeiro e último nome na ordenação alfabética.
Depois inclui municípios nos quantis de código:
10%;
25%;
50%;
75%;
90%.
Também inclui:
ao menos um município de cada região geográfica intermediária encontrada;
um nome contendo caracteres acentuados;
um nome composto com espaço.
As duplicidades são removidas por código e o resultado é ordenado deterministicamente.
Cada município da amostra é validado simultaneamente por:
ibge_geocodigo(codigo=...)
ibge_localidade(codigo=...)O gate compara código, nome e UF retornados pelas ferramentas com o registro oficial usado como referência.
Artefatos produzidos pelo gate
A execução gera:
snapshot-candidato.json;meta.json;validacao-645.jsonl;amostra.json;amostra-resultados.json;resumo.json.
O snapshot é serializado de forma determinística e recebe SHA-256. A promoção para snapshot versionado só é permitida se não houver divergência estrutural nem falha na amostra real.
Comando:
npm run gate:sp-645Arquitetura
flowchart LR
A[Cliente MCP remoto] -->|Streamable HTTP| B[Cloudflare Worker]
A2[Cliente MCP local] -->|STDIO| C[Servidor local]
B --> D[buildServer / registerAll]
C --> D
D --> E{Ferramenta}
E --> F[Localidades / Cidades / CNAE / Países]
E --> G[SIDRA / Censo / Indicadores / Saúde]
E --> H[Malhas / Vizinhos]
E --> I[Recortes temáticos]
E --> J[search / fetch]
F --> K[APIs oficiais IBGE]
G --> K
H --> K
I --> L[Snapshots oficiais versionados]
J --> K
D --> M[Validação + cache + métricas]
K --> N[Adapter de domínio]
L --> N
N --> O[Procedência]
O --> P[content + structuredContent + _meta]A mesma lógica de registro das ferramentas é usada pelo servidor STDIO e pelo Worker HTTP. O Worker acrescenta controles de transporte, segurança e operação, mas não mantém uma implementação paralela das regras de domínio.
Árvore funcional
src/
server.ts registro MCP e instruções
cache.ts cache TTL e metadata de extração
retry.ts retry, timeout e erros upstream
provenance.ts adapter de procedência IBGE
stats.ts adapter estatístico SIDRA
pagination.ts guarda de cursor
validation.ts validações compartilhadas
tools/ ferramentas de domínio
data/recortes/ snapshots territoriais versionados
worker/
src/ transporte Cloudflare
tests/ testes do Worker
scripts/ smoke e testes HTTP
wrangler.jsonc configuração de deploy
scripts/
gate-sp-645.mjs validação dos 645 municípios de SP
normalizar_recortes.py ETL dos recortes territoriais
smoke-mcp.mjs smoke STDIO/HTTP
run_integration_gate.ps1 contratos reais
tests/ testes unitários e de integração
evals/ avaliação de seleção de ferramentas
baselines/ superfície MCP versionada
docs/ arquitetura, auditorias e metodologiaFerramentas disponíveis
Para schemas, parâmetros, decisões, fontes e limitações ferramenta por ferramenta, consulte docs/FERRAMENTAS.md. Para a visão consolidada de origem, cache e derivação, consulte docs/MATRIZ_FONTES_E_PROCESSOS.md.
Domínio | Ferramentas |
Localidades |
|
SIDRA |
|
Censo e indicadores |
|
Geografia |
|
Economia/classificações |
|
Saúde e condições de vida |
|
Nomes |
|
Países |
|
Informação corrente |
|
Pesquisa assistida |
|
Seleção recomendada
Pergunta | Ferramenta |
Panorama de um município |
|
Censo por tema |
|
Série econômica/social conhecida |
|
Comparar localidades |
|
Consultar tabela SIDRA |
|
Descobrir tabela |
|
Inspecionar dimensões/classificações |
|
Resolver nome/código IBGE |
|
Geometria administrativa |
|
Mapa coroplético municipal |
|
Vizinhança municipal |
|
Recorte territorial especial |
|
Fluxo de uma chamada
flowchart TD
A[tools/call] --> B[Schema Zod estrito]
B -->|inválido| C[Erro explícito]
B -->|válido| D[Handler]
D --> E{Origem}
E -->|API| F[cachedFetch]
E -->|snapshot| G[JSON versionado]
F --> H[fetchWithRetry]
H --> I[Resposta oficial]
G --> I
I --> J[Adapter de domínio]
J --> K{estatísticas?}
K -->|sim| L[mcp-stats]
K -->|não| M[resultado de domínio]
L --> M
M --> N[provenienciaIbge]
N --> O[toMcpResult]
O --> P[content]
O --> Q[structuredContent]
O --> R[_meta]A política do projeto é recusar ambiguidades relevantes em vez de escolher silenciosamente uma interpretação plausível.
Algoritmos e regras de decisão
1. Validação territorial
isValidIbgeCode interpreta o tamanho do código:
1 dígito → região;
2 dígitos → UF;
7 dígitos → município;
9 dígitos → distrito.
Para municípios e distritos, os dois primeiros dígitos precisam corresponder a uma UF oficial conhecida.
2. Normalização de UF
Entradas como:
SP
São Paulo
35são resolvidas por um único resolver compartilhado, evitando lógicas divergentes entre ferramentas.
3. Resolução em ibge_geocodigo
Quando recebe codigo, a ferramenta remove caracteres não numéricos e decide o nível territorial pelo comprimento.
Quando recebe nome:
verifica correspondência com UF;
verifica correspondência com região;
consulta municípios;
restringe por UF, quando informada;
usa busca textual por inclusão do nome;
limita a 20 correspondências;
se houver exatamente uma correspondência, retorna imediatamente a hierarquia detalhada;
se houver várias, retorna lista e exige escolha explícita.
A ferramenta não usa correspondência fuzzy probabilística para inventar uma localidade.
4. Datas
Entradas aceitas:
DD/MM/AAAA;DD-MM-AAAA;AAAA-MM-DD.
A ordem mês-dia-ano fornecida pelo usuário não é aceita por ser ambígua no contexto brasileiro.
Quando uma API do IBGE exige MM-DD-AAAA, a conversão é feita somente depois da validação da entrada.
5. Períodos SIDRA
São aceitos, entre outros:
last;first;all;last N;ano
AAAA;intervalo
AAAA-AAAA;mês
AAAAMM;trimestre no formato usado pelo SIDRA;
múltiplos períodos separados por vírgula.
6. Paginação MCP
As listas MCP atuais são entregues em página única e não emitem nextCursor.
Por isso, se o cliente envia cursor em:
tools/list;resources/list;resources/templates/list;prompts/list;
o servidor responde JSON-RPC -32602 Invalid params, em vez de ignorar um cursor inválido.
7. Algoritmos delegados
Alguns algoritmos não são reimplementados localmente:
estatística genérica →
@sbissoli/mcp-stats;ranking do índice
search→@sbissoli/mcp-search;modelo canônico de procedência →
@sbissoli/mcp-provenance;contiguidade topológica →
@turf/boolean-touches;centróide →
@turf/centroid;distância geodésica →
@turf/distance.
O CensoSenso implementa os adapters, regras de decisão, seleção de colunas, tratamento de erros, fontes, schemas e contratos ao redor desses algoritmos.
Extração, cache e tolerância a falhas
Cache
O cache é em memória por processo/isolate.
TTL padrão:
Classe | TTL |
| 24 horas |
| 1 hora |
| 15 minutos |
| 1 minuto |
A chave de cache é construída com parâmetros:
parâmetros
undefinedsão removidos;nomes são ordenados lexicograficamente;
a representação
k=vé concatenada à base.
Isso evita chaves distintas para a mesma consulta apenas por diferença na ordem dos parâmetros.
Data real de extração
Cada entrada de cache preserva a data do fetch real.
Em cache hit:
o valor pode ser servido novamente;
served_from_cache=true;retrieved_atcontinua sendo o instante original de obtenção upstream.
Isso evita declarar como “extraído agora” um dado que foi obtido anteriormente.
Retry
Padrão:
máximo: 4 retries além da tentativa inicial;
atraso inicial: 2.000 ms;
multiplicador: 2;
atraso máximo: 16.000 ms.
Fórmula:
delay = min(initialDelay × multiplier^(attempt-1), maxDelay)Status HTTP retryable:
429, 500, 502, 503, 504Também são considerados transitórios erros de rede como:
ECONNREFUSED;ECONNRESET;ETIMEDOUT;ENOTFOUND;EAI_AGAIN;conexão recusada/resetada;
timeout.
Cada tentativa recebe AbortSignal próprio e timeout configurável.
Erros da fonte
Quando uma API devolve erro:
o código HTTP é preservado;
o corpo textual é lido;
páginas HTML de borda são descartadas;
JSON de erro é inspecionado por
message,mensagem,erro,erroroudetail;espaços são normalizados;
o texto é truncado em 300 caracteres.
A intenção é devolver ao cliente a razão fornecida pela fonte — por exemplo, “nível territorial incompatível” — em vez de reduzir tudo a “HTTP 400”.
Procedência e auditabilidade
O CensoSenso usa um adapter sobre @sbissoli/mcp-provenance.
Contexto:
namespace:
io.github.hilaliskandar.censosenso;locale:
pt-BR;timezone: Brasília, UTC-03:00;
modo padrão:
concise.
A procedência pode ser emitida em três canais:
structuredContent.provenance;structuredContent.attribution;_metanamespaced.
O Markdown legível também pode receber rodapé compacto.
Fontes registradas
Entre as fontes oficiais usadas:
API de Localidades;
SIDRA;
API de Agregados;
API de Nomes;
API de Malhas;
GeoFTP;
API de Notícias;
Projeções de População;
CNAE;
Calendário;
Países;
Pesquisas/Cidades@.
Derivação
Regra:
filtrar, paginar ou reserializar dado bruto → não é derivação estatística;
calcular média, mediana, percentis, rankings ou agregações → resultado marcado como derivado e acompanhado de nota metodológica.
SIDRA e estatísticas
Fluxo recomendado
ibge_sidra_tabelas
↓
ibge_sidra_metadados
↓
ibge_sidraWrappers especializados simplificam temas frequentes:
ibge_censo;ibge_indicadores;ibge_datasaude;ibge_comparar;ibge_cidades.
Estatísticas sobre o conjunto completo
Quando estatisticas=true, o cálculo ocorre antes da paginação/truncagem.
São produzidos:
n;
soma;
mínimo;
máximo;
média;
mediana;
desvio-padrão;
percentis;
top;
bottom.
Marcadores SIDRA excluídos da distribuição:
-
..
...
XValores não numéricos também ficam fora de n e são contabilizados em registrosSemValor.
Resolução de agruparPor
A coluna solicitada é resolvida nesta ordem:
correspondência exata sem diferença de caixa/acento;
aliases conhecidos;
correspondência parcial bidirecional;
se houver mais de uma candidata, a operação é recusada como ambígua.
Exemplos de aliases:
UF,estado→Unidade da Federação;cidade→Município;região→Grande Região;indicador→Variável.
Quando SIDRA publica simultaneamente “Unidade da Federação” e “Unidade da Federação (Código)”, o rótulo legível é preferido porque os grupos são semanticamente equivalentes.
Mistura de variáveis
Se uma consulta traz várias variáveis e o usuário não escolhe agrupamento, o servidor agrupa automaticamente por Variável para evitar calcular uma única distribuição sobre unidades potencialmente incompatíveis.
Geografia, vizinhança e recortes territoriais
Malhas administrativas
ibge_malhas consulta a API oficial de Malhas para geometrias administrativas.
Mapas coropléticos
ibge_mapa combina indicadores municipais auditados do SIDRA com a malha municipal oficial do IBGE e produz SVG vetorial para recortes explícitos de até 50 municípios de uma mesma UF. A primeira versão oferece classificação por quantis ou intervalos iguais e registra o produto como derivado.
Vizinhança municipal
Sem raio:
geometria do município
↓
candidatos territoriais
↓
@turf/boolean-touches
↓
municípios topologicamente contíguosNeste modo, “vizinho” significa tocar a fronteira do município.
Com raio:
geometria
↓
centroid
↓
distance
↓
filtro por kmEsse modo é aproximação por distância entre centróides e é declarado como tal.
Recortes temáticos
A auditoria do projeto encontrou bloqueio HTTP 403 no WFS temático para clientes automatizados. Para evitar que uma origem instável fizesse parte do caminho crítico, os atributos e composições foram migrados para snapshots oficiais versionados.
Fluxo:
fonte oficial IBGE/GeoFTP
↓
inspeção de arquivo
↓
validação de estrutura/vintage/encoding
↓
normalização
↓
JSON versionado
↓
recortes-gerados.ts
↓
ibge_malhas_temaRecortes atualmente versionados:
Amazônia Legal 2024;
Biomas 2025;
Semiárido 2022;
Zona Costeira 2021;
Faixa de Fronteira 2024;
Regiões Metropolitanas 2025;
RIDEs 2025.
A ferramenta retorna composição e atributos. Geometria administrativa continua em ibge_malhas.
Pesquisa assistida search/fetch
O índice de pesquisa é construído na primeira chamada e agrega:
catálogo SIDRA;
municípios;
indicadores conhecidos;
temas do Censo;
indicadores de saúde;
recortes territoriais.
A construção consulta em paralelo:
catálogo oficial de agregados;
lista nivelada de municípios.
Depois acrescenta os dicionários auditados locais.
O índice possui TTL equivalente a CACHE_TTL.STATIC — 24 horas.
Chamadas simultâneas durante a primeira construção compartilham a mesma Promise, evitando reconstruções concorrentes.
Se a construção falha, o resultado falho não é mantido: a próxima chamada tenta novamente.
search
O ranking genérico é fornecido por @sbissoli/mcp-search. O CensoSenso define:
entradas;
títulos;
palavras-chave;
URLs;
vocabulário de consulta;
fontes;
limite de resultados.
fetch
O ID do resultado determina qual ferramenta real renderiza o documento:
tabela SIDRA → metadados SIDRA;
município → hierarquia + população;
tema Censo → catálogo auditado;
saúde → indicador auditado;
recorte → snapshot versionado;
indicador geral → ferramenta de indicadores.
Assim, fetch não inventa um documento independente: ele recompõe a informação usando os mesmos adapters e contratos das ferramentas de domínio.
Validação, testes e gates
O projeto separa testes determinísticos de contratos que dependem de fontes externas.
Gate completo
npm run gate:deployEncadeia:
checagem do gerador de homologação;
typecheck;
lint;
EOL;
Prettier;
build;
suíte Vitest;
cobertura;
npm cido Worker;typecheck do Worker;
testes do Worker.
Gate dos 645 municípios
npm run gate:sp-645Integração real
Em PowerShell:
.\scripts\run_integration_gate.ps1Smoke
STDIO:
node scripts/smoke-mcp.mjs --stdioRemoto:
node scripts/smoke-mcp.mjs https://censosenso.poderdapalavra.orgBaseline da superfície MCP
node scripts/dump-surface.mjs --stdioBaseline atual:
baselines/surface-stdio-0.7.0.jsonMudança de ferramentas, schemas, resources ou prompts deve produzir diff explícito no baseline.
Instalação local
A árvore homologada do protótipo 0.7.0 está publicada neste repositório. O CI público usa apenas runners hospedados pelo GitHub e não realiza deploy de produção.
Pré-requisitos:
Git;
Node.js 22 ou superior;
npm compatível com o lockfile;
Python somente se for necessário regenerar snapshots territoriais.
Clone:
git clone https://github.com/hilaliskandar/hilaliskandar-censosenso-mcp.git
cd hilaliskandar-censosenso-mcp
npm ciBuild:
npm run buildExecução STDIO:
node dist/index.jsOu:
npm startConfiguração genérica de um cliente MCP local:
{
"mcpServers": {
"censosenso": {
"command": "node",
"args": ["/caminho/para/hilaliskandar-censosenso-mcp/dist/index.js"]
}
}
}A forma exata do arquivo de configuração varia entre clientes MCP.
Uso remoto
Clientes compatíveis com MCP Streamable HTTP devem apontar para:
https://censosenso.poderdapalavra.org/mcpO protótipo público 1:
não exige conta CensoSenso;
não exige OAuth;
não exige API key;
é somente leitura.
Exemplos de intenção
Qual era a população de Campinas no Censo 2022?
Liste os municípios do Espírito Santo.
Compare a população de Campinas, Jundiaí e Sorocaba.
Quais municípios fazem fronteira com Guararema?
Qual é o índice de envelhecimento de Campinas?
Liste os municípios da Amazônia Legal.Exemplos de chamadas
ibge_geocodigo(nome="Campinas", uf="SP")
ibge_censo(ano="2022", tema="estrutura_etaria", nivel_territorial="6", localidades="3509502")
ibge_vizinhos(municipio="3518305")
ibge_malhas_tema(tema="amazonia_legal")Desenvolvimento e reprodução
Worker local:
cd worker
npm ci
npm run devA equivalência funcional de uma reprodução exige, no mínimo:
npm ci;npm run gate:deploy;negociação MCP via STDIO;
negociação MCP via Worker;
tools/listcom superfície esperada;ao menos uma chamada real ao IBGE;
procedência nos canais esperados;
integridade dos snapshots;
ausência de mudança inexplicada no baseline;
resposta válida de
/health,/statuse/mcp.
CI/CD
Fluxo operacional:
push/merge
↓
GitHub
↓
gates
↓
Cloudflare Workers Build
↓
wrangler deploy
↓
health/status/MCPSegurança, privacidade e limites operacionais
Modelo de segurança
ferramentas de dados são read-only;
schemas de entrada são estritos;
Host/Origin são validados no transporte;
HTTPS via Cloudflare;
Bearer opcional existe no código;
OAuth não está habilitado;
/metricsé privado por padrão.
Sem METRICS_API_KEY, /metrics responde:
HTTP 404 Not FoundEsse comportamento foi confirmado no domínio de produção antes da abertura pública.
Rate limiting
O Worker usa token bucket em memória por cliente/IP.
Configuração atual:
burst: 20 tokens;
refill: 5 tokens/s;
máximo: 1.000 buckets por isolate;
evicção FIFO quando o mapa atinge o limite.
Importante: esse limite é por isolate. Não constitui cota global exata.
Telemetria
O projeto pode manter:
contadores agregados no Durable Object
USAGE;logs de método, path, status e duração;
metadata de deploy;
cache em memória.
O código não foi projetado para persistir nos contadores de uso:
valores de argumentos;
conteúdo das perguntas;
datasets retornados.
Leia PRIVACY.md e SECURITY.md.
Limitações
sem SLA;
disponibilidade depende de APIs oficiais externas;
o WFS temático permanece fora do runtime principal;
rate limit não é global;
OAuth ainda não está habilitado;
pacote npm ainda não publicado;
o protótipo pode mudar de contrato em versões posteriores.
Dados, licença e atribuições
Software
Licença: MIT.
Copyright:
Copyright (c) 2026 Carlos Alexandre Gomes <hilaliskandar@gmail.com>Código de origem
Partes deste projeto derivam de:
IBGE Brasil MCP / ibge-br-mcp
Autor original: Sidney da Silva Pereira Bissoli
Repositório: https://github.com/SidneyBissoli/ibge-br-mcp
Licença: MIT.
O aviso MIT original é preservado em THIRD_PARTY_LICENSES.md.
A linhagem e as responsabilidades estão descritas em NOTICE.md.
Dados
O software consulta dados públicos oficiais do IBGE.
A licença MIT deste repositório cobre o software e não substitui os termos aplicáveis aos dados e serviços oficiais consultados.
O CensoSenso:
não é produto oficial do IBGE;
não representa o IBGE;
não implica endosso do IBGE.
Status do protótipo e próximos passos
Concluído:
versão 0.7.0;
24 ferramentas;
transporte STDIO;
Streamable HTTP;
domínio próprio;
homologação remota;
procedência estruturada;
snapshots territoriais;
CI/gates;
hardening de
/metrics;validação dos 645 municípios paulistas;
documentação de segurança e privacidade;
licença e atribuições públicas.
Antes da divulgação ampla:
publicar a árvore homologada completa neste repositório;
executar novamente o gate completo na árvore pública;
executar smoke remoto após a migração;
criar tag/release pública;
iniciar com um grupo externo reduzido;
monitorar erros, uso e rate limiting;
ampliar a divulgação somente após janela inicial estável.
Itens deliberadamente posteriores:
publicação npm;
OAuth obrigatório;
rate limit global rígido;
eventual retorno do WFS temático ao runtime.
Contato
Carlos Alexandre Gomes
GitHub: @hilaliskandar
E-mail: hilaliskandar@gmail.com
Para vulnerabilidades, consulte SECURITY.md. Para contribuições, consulte CONTRIBUTING.md.
Available Tools
24 toolsfetchDocumento para Deep ResearchARead-onlyIdempotent
Returns the full document for an id obtained from search, as { id, title, text, url, metadata }: text is the readable content (Markdown) and url the canonical public page to cite.
Companion of search in the OpenAI Deep Research contract, over the IBGE (Brazilian official statistics: SIDRA tables, municipalities, known indicators) catalog. Only ids returned by search are valid; an unknown id returns an error.
The ibge_* tools (ibge_sidra, ibge_cidades, ibge_indicadores, ibge_comparar…) remain the tools for data queries.
Behavior: read-only and idempotent — a live GET against the public source when the document needs it.
Inputs: id (required). Returns: id, url, text, title, +1 more
ibge_calendarioCalendário de divulgaçõesARead-onlyIdempotent
Queries IBGE release and collection calendar.
Features:
List upcoming survey releases
Filter by product (IPCA, PNAD, GDP, etc.)
Filter by period
Distinguish releases from field collections
Event types:
Release: Publication of survey results
Collection: Field research period
Examples:
Upcoming releases: (no parameters)
IPCA releases: produto="IPCA"
2024 calendar: de="01/01/2024", ate="31/12/2024"
Field collections: tipo="coleta"
Use a different tool when:
Already-published news and releases → ibge_noticias
Behavior: read-only and idempotent — a live GET against the public IBGE Calendário API. Returns a Markdown list.
Inputs: de, ate, tipo, pagina, +2 more. Returns: total, pagina, eventos, produto, +3 more
ibge_censoCenso DemográficoARead-onlyIdempotent
Queries IBGE Demographic Census data (1970-2022).
Simplified tool to access census data without knowing SIDRA table codes.
Available years: 1970, 1980, 1991, 2000, 2010, 2022
Available themes:
populacao: Resident population
alfabetizacao: Literacy rate
domicilios: Housing characteristics
idade_sexo: Age pyramid
religiao: Religion distribution
cor_raca: Race/color
rendimento: Monthly income
educacao: Education level
trabalho: Employment
Examples:
Population 2022: ano="2022", tema="populacao"
Historical series: ano="todos", tema="populacao"
Literacy 2010 by state: ano="2010", tema="alfabetizacao", nivel_territorial="3"
List tables: tema="listar"
Statistics mode: for largest/smallest/mean/median/distribution/ranking questions over census data ("which municipality had the largest 2022 population?") use estatisticas=true — full distribution + top/bottom computed over ALL rows before truncation; agruparPor="" ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.
Use a different tool when:
One municipality's current panel (estimate, HDI, GDP) → ibge_cidades
Current estimates or non-census indicator time series → ibge_indicadores
Comparing/ranking localities → ibge_comparar
An arbitrary SIDRA table → ibge_sidra
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
Inputs: ano, tema, topN, campos, +5 more. Returns: ano, tema, tabela, colunas, +6 more
ibge_cidadesPanorama municipal (Cidades@)ARead-onlyIdempotent
Queries municipal indicators from IBGE (similar to Cidades@ portal).
Features:
General overview of a municipality (population, HDI, GDP, etc.)
Query specific indicators
Historical indicator data over years
List available surveys and indicators
Available indicators: populacao, area, densidade, pib_per_capita, idh, escolarizacao, mortalidade, salario_medio, receitas, despesas
Examples:
São Paulo overview: tipo="panorama", municipio="3550308"
Population history: tipo="historico", municipio="3550308", indicador="populacao"
View surveys: tipo="pesquisas"
Available indicators: tipo="indicador"
This tool is the panel for a SINGLE municipality (Cidades@). Use a different tool when:
Census themes / historical series → ibge_censo
Comparing multiple municipalities → ibge_comparar
A macro indicator time series → ibge_indicadores
Behavior: read-only and idempotent — uses the public IBGE Pesquisas (Cidades@) API, Localidades, SIDRA Table 9510 for salario_medio (municipal publication restricted to municipalities with 50,000 inhabitants or more), and the versioned official Atlas Brasil Censo 1991–2010 snapshot for IDHM Educação, Longevidade and Renda. Panorama may combine several indicator calls and explicitly reports partial upstream gaps. Returns Markdown plus a typed structuredContent payload.
Inputs: uf, tipo, pesquisa, indicador, +1 more. Returns: nome, tipo, avisos, municipio, +3 more
ibge_cnaeClassificação CNAEARead-onlyIdempotent
Queries CNAE (National Classification of Economic Activities) from IBGE.
CNAE is the official classification for economic activities in Brazil.
Hierarchical structure:
Section (letter A-U): 21 main categories
Division (2 digits): 87 divisions
Group (3 digits): 285 groups
Class (4-5 digits): 673 classes
Subclass (7 digits): 1,332 subclasses
Features:
Search by CNAE code
Search by activity description
List by hierarchical level
Show complete hierarchy
Examples:
Search software: busca="software"
Specific code: codigo="6201-5/01"
View section: codigo="J"
List divisions: nivel="divisoes"
Behavior: read-only and idempotent — a live GET against the public IBGE CNAE API. Returns Markdown.
Inputs: busca, nivel, codigo, limite. Returns: modo, busca, lista, codigo, +2 more
ibge_compararComparação entre localidadesARead-onlyIdempotent
Compares data between localities (municipalities or states).
Available indicators:
populacao: Current population estimate
populacao_censo: Census 2022 population
pib: GDP per capita
area: Territorial area (km²)
densidade: Population density (inhab/km²)
alfabetizacao: Literacy rate
domicilios: Number of households
Features:
Compare up to 10 localities at once
Calculate statistics (max, min, average, variation)
Generate ranked output
Accept municipality codes (7 digits) or state codes (2 digits)
Examples:
Compare capitals: localidades="3550308,3304557,4106902", indicador="populacao"
Compare states: localidades="35,33,41", indicador="pib"
Area ranking: localidades="3550308,3304557", formato="ranking"
List indicators: indicador="listar"
Use a different tool when:
You want a time series or one known indicator rather than comparing a fixed set of localities → ibge_indicadores
You need census themes or historical census data → ibge_censo
You know the exact SIDRA table and need arbitrary dimensions → ibge_sidra
Use this tool ONLY to rank/compare 2–10 localities on one indicator. For a single locality, use ibge_cidades (municipal panel), ibge_censo, or ibge_sidra.
Behavior: read-only and idempotent — a live GET against the public IBGE APIs (SIDRA and Localidades). Returns Markdown plus a typed structuredContent payload.
Inputs: localidades (required), formato, indicador. Returns: nome, tabela, formato, indicador, +4 more
ibge_datasaudeIndicadores de saúdeARead-onlyIdempotent
Queries Brazil health indicators, served through IBGE's SIDRA (some originally produced by DataSUS, e.g. mortality and births).
Mortality and Birth:
mortalidade_infantil: Infant mortality rate
nascidos_vivos: Live births by location
obitos: Deaths by residence
Demographic Indicators:
esperanca_vida: Life expectancy at birth
fecundidade: Fertility rate
Sanitation:
saneamento_agua: Water supply
saneamento_esgoto: Sewage system
Health Coverage:
plano_saude: Health insurance coverage
autoavaliacao_saude: Self-rated health status
Territorial levels: 1=Brazil, 2=Region, 3=State, 6=Municipality
Use this tool for health, mortality, fertility, sanitation and health-coverage indicators. Use ibge_indicadores for general economic/social series such as GDP, prices, labor and population estimates.
Examples:
Infant mortality: indicador="mortalidade_infantil"
Life expectancy by state: indicador="esperanca_vida", nivel_territorial="3"
Deaths in SP: indicador="obitos", nivel_territorial="3", localidade="35"
List indicators: indicador="listar"
Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest infant mortality?", "median life expectancy across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="" ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.
Use a different tool when:
A single municipality's general panel (which also includes infant mortality) → ibge_cidades
Population/demographic counts (not health-specific) → ibge_censo or ibge_sidra
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
Inputs: indicador (required), topN, campos, formato, +5 more. Returns: nome, fonte, colunas, indicador, +5 more
ibge_estadosEstados do BrasilARead-onlyIdempotent
Lists all Brazilian states from IBGE.
Features:
Lists all 27 states (26 states + Federal District)
Filter by region (North, Northeast, Southeast, South, Central-West)
Sort by ID, name, or abbreviation
Examples:
List all states: (no parameters)
Northeast states: regiao="NE"
Sorted by abbreviation: ordenar="sigla"
Use a different tool when:
Municipalities of a state → ibge_municipios
Details/hierarchy of one locality by code → ibge_localidade
Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown table.
Inputs: regiao, ordenar. Returns: total, estados, provenance, attribution
ibge_geocodigoCódigos geográficos do IBGEARead-onlyIdempotent
Decodes IBGE codes or searches codes by locality name.
Features:
Decode region, state, municipality, or district codes
Search IBGE code by name
Show complete geographic hierarchy
Return related codes
Code structure:
1 digit: Region (1=North, 2=Northeast, 3=Southeast, 4=South, 5=Central-West)
2 digits: State (11-53)
7 digits: Municipality
9 digits: District
Examples:
Decode municipality: codigo="3550308"
Decode state: codigo="35"
Search by name: nome="São Paulo"
Municipality in state: nome="Campinas", uf="SP"
This tool decodes a code's structure and resolves name→code at any level. Use a different tool when:
You only need to list/search municipalities → ibge_municipios
You want the full detailed record of one locality → ibge_localidade
Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns Markdown.
Inputs: uf, nome, codigo. Returns: nome, tipo, sigla, total, +9 more
ibge_indicadoresIndicadores econômicos e sociaisARead-onlyIdempotent
Queries IBGE economic and social indicators.
Available indicators:
Economic:
pib: GDP at current prices
pib_variacao: GDP variation (%)
pib_per_capita: GDP per capita
industria: Industrial production
comercio: Retail sales
servicos: Services volume
Prices:
ipca: Monthly IPCA
ipca_acumulado: 12-month IPCA
inpc: Monthly INPC
Labor:
desemprego: Unemployment rate
ocupacao: Employed people
rendimento: Average income
informalidade: Informality rate
Population:
populacao: Population estimate
densidade: Population density
Examples:
GDP: indicador="pib"
IPCA last 12 months: indicador="ipca", periodos="last 12"
Unemployment by state: indicador="desemprego", nivel_territorial="3"
List indicators: indicador="listar"
Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest unemployment?", "median GDP per capita across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="" (e.g. "Unidade da Federação", "Trimestre") ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.
Use a different tool when:
Comparing/ranking localities → ibge_comparar
Census themes → ibge_censo
One municipality's panel → ibge_cidades
You know the exact SIDRA table or need arbitrary variables/classifications → ibge_sidra
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
Inputs: topN, campos, formato, periodos, +6 more. Returns: nome, tabela, colunas, indicador, +5 more
ibge_localidadeDetalhes de localidadeARead-onlyIdempotent
Returns details of a specific locality by IBGE code.
Features:
State information (2-digit code)
Municipality information (7-digit code)
District information (9-digit code)
Complete hierarchy (region, mesoregion, microregion)
Examples:
São Paulo state: codigo=35
São Paulo city: codigo=3550308
District: codigo=355030805
This tool returns the full record of ONE locality you already have the code for. Use a different tool when:
You have a name and need the code → ibge_municipios (municipalities) or ibge_geocodigo (any level)
You want to decompose/understand a code's structure → ibge_geocodigo
Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown record.
Inputs: codigo (required), tipo. Returns: id, nome, tipo, sigla, +9 more
ibge_malhasMalhas geográficasARead-onlyIdempotent
Gets geographic meshes (maps) from IBGE in GeoJSON, TopoJSON, or SVG format.
Features:
Meshes for Brazil, regions, states, municipalities
Different resolution levels (internal divisions)
Different quality levels
Formats: GeoJSON (data), TopoJSON (compact), SVG (image)
Structured cartographic summary for geometric responses: feature count, geometry types, bbox, vertex centroid, and property keys
Locality types:
"BR" or "1" = Entire Brazil
State abbreviation (e.g., "SP", "RJ")
State code (e.g., "35" for SP)
Municipality code (7 digits)
Resolution (internal divisions):
0 = Outline only
2 = States
5 = Municipalities
Examples:
Brazil with states: localidade="BR", resolucao="2"
São Paulo with municipalities: localidade="SP", resolucao="5"
SVG format: localidade="BR", formato="svg"
Use a different tool when:
Thematic meshes (biomes, Legal Amazon, semi-arid, metropolitan regions) → ibge_malhas_tema
Behavior: read-only and idempotent — a live GET against the public IBGE Malhas API. The full geometry remains in the Markdown/download channel; structuredContent carries lightweight cartographic metadata only.
Inputs: localidade (required), tipo, formato, qualidade, +2 more. Returns: url, tipo, formato, qualidade, +6 more
ibge_malhas_temaMalhas temáticasARead-onlyIdempotent
Lists what a THEMATIC territorial recorte of Brazil contains: how many records, with which codes and names, from versioned official IBGE/GeoFTP snapshots.
Available recortes:
biomas: the six continental biomes
amazonia_legal: Legal Amazon boundary
semiarido: semi-arid area
costeiro: coastal municipalities
fronteira: border-strip municipalities
metropolitana: metropolitan regions
ride: Integrated Development Regions
listar: the catalogue itself, without querying the source
Filtering with codigo: biomas uses the biome code; every municipality-composition recorte (amazonia_legal, semiarido, costeiro, fronteira, metropolitana and ride) accepts the 7-digit IBGE municipality code. Ask without codigo to list records.
THEMATIC GEOMETRY IS NOT PART OF THIS TOOL'S CONTRACT. Use ibge_malhas for supported administrative geometry.
Use a different tool when:
Administrative meshes WITH geometry (country/region/state/municipality outlines) → ibge_malhas
Behavior: read-only and idempotent. Attributes/listings come exclusively from versioned official IBGE/GeoFTP snapshots audited by the laboratory. Returns Markdown plus a typed structuredContent payload.
Inputs: tema (required), codigo, limite. Returns: tema, temas, codigo, versao, +7 more
ibge_mapaMapa coroplético municipalARead-onlyIdempotent
Generates a municipal choropleth map as SVG from audited SIDRA indicators and official IBGE municipal meshes.
Scope of this first cartographic release:
2 to 50 municipalities
all municipalities must belong to the same state
indicators: populacao, populacao_censo, pib, area, densidade, alfabetizacao, domicilios
classification: quantiles or equal intervals
output: lightweight metadata plus complete SVG in structuredContent.svg
The SVG includes municipal polygons, sequential classes, legend, title, tooltips and source note. The server fetches the state municipal mesh at minimum quality and filters it to the requested municipalities.
Use a different tool when:
You need only geometry/download URL → ibge_malhas
You need non-cartographic comparison/ranking → ibge_comparar
You need thematic territorial composition (biomes, metropolitan regions, etc.) → ibge_malhas_tema
Behavior: read-only and idempotent. The map is a server-side derived product from official IBGE SIDRA data and official IBGE geographic meshes.
Inputs: municipios (required), titulo, classes, largura, +2 more. Returns: svg, bbox, nome, fontes, +7 more
ibge_municipiosMunicípios do BrasilARead-onlyIdempotent
Lists Brazilian municipalities from IBGE.
Features:
List municipalities by state (using state abbreviation)
List all municipalities in Brazil (5,570 municipalities)
Search by municipality name
Returns 7-digit IBGE code
Examples:
São Paulo municipalities: uf="SP"
Search by name: busca="Campinas"
MG municipalities containing "Belo": uf="MG", busca="Belo"
Use a different tool when:
Resolve/decode a code at any level (region, state, district), not just municipalities → ibge_geocodigo
Full details/hierarchy of one locality by code → ibge_localidade
Neighboring municipalities → ibge_vizinhos
Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown table.
Inputs: uf, busca, limite. Returns: uf, busca, total, municipios, +2 more
ibge_nomesFrequência e ranking de nomesARead-onlyIdempotent
Queries name frequency and rankings in Brazil (IBGE).
Features:
Name frequency (tipo='frequencia'):
Birth frequency by decade
Multiple names separated by comma
Filter by sex and locality
Name ranking (tipo='ranking'):
Most popular names
Filter by decade, sex, and locality
Available decades: 1930-2010
Examples:
Frequency of "Maria": tipo="frequencia", nomes="Maria"
Compare names: tipo="frequencia", nomes="João,José,Pedro"
2000s ranking: tipo="ranking", decada=2000
Female names: tipo="ranking", sexo="F"
Behavior: read-only and idempotent — a live GET against the public IBGE Nomes (Censo) API. Returns a Markdown table.
Inputs: tipo (required), sexo, nomes, decada, +2 more. Returns: tipo, ranking, frequencia, provenance, +1 more
ibge_noticiasNotícias do IBGEARead-onlyIdempotent
Searches and lists already-published IBGE news articles and press releases.
Use this to find recent IBGE publications or announcements about a survey or topic — when an indicator was released, or news mentioning a term like "censo". Results are sorted newest-first; with no parameters it returns the 10 most recent items.
Parameters:
busca: free-text term to match (e.g. "PIB", "censo")
tipo: "release" (official publication of survey results) or "noticia" (general news); omit for both
de / ate: date range, format DD/MM/AAAA (e.g. de="01/01/2024", ate="31/12/2024")
destaque: true to return only featured items
quantidade: how many to return (default 10, max 100); pagina: page number to page through more
Each item returns: title, type (release/news), publication date, editoria (section), related products/surveys, a featured flag, a plain-text summary, and a link to the full article. The header reports the total count and current page.
Examples:
Latest 10 news: (no parameters)
Search census: busca="censo"
2024 news: de="01/01/2024", ate="31/12/2024"
Releases only: tipo="release"
Use a different tool when:
Scheduled/upcoming release dates (not yet published) → ibge_calendario
Behavior: read-only and idempotent — a live GET against the public IBGE Notícias API. Returns a Markdown list.
Inputs: de, ate, tipo, busca, +3 more. Returns: busca, total, pagina, noticias, +3 more
ibge_paisesDados de paísesARead-onlyIdempotent
Queries international country data via IBGE.
Features:
List all countries (following UN M49 methodology)
Country details (area, languages, currency, location)
Search countries by name
Filter by region/continent
Available regions: americas, europa, africa, asia, oceania
Country codes: Use ISO-ALPHA-2 (e.g., BR, US, AR, PT, JP)
Examples:
List all: tipo="listar"
Brazil details: tipo="detalhes", pais="BR"
Search: tipo="buscar", busca="Argentina"
Americas countries: tipo="listar", regiao="americas"
Available indicators: tipo="indicadores"
Behavior: read-only and idempotent — queries the public IBGE Países API when data is requested and returns Markdown plus typed structuredContent with provenance.
Inputs: pais, tipo, busca, regiao, +1 more. Returns: pais, tipo, busca, total, +5 more
ibge_pesquisasPesquisas do IBGEARead-onlyIdempotent
Lists available IBGE surveys and their tables.
Features:
List all IBGE surveys (Census, PNAD, GDP, etc.)
Search by name or code
Show details and tables of a specific survey
Categorize surveys by theme
Main surveys:
Census: Demographic, Agricultural, MUNIC
PNAD Contínua: Employment, income, education
National Accounts: GDP, investments
Economic Surveys: Industry, Commerce, Services
Price Indices: IPCA, INPC
Examples:
List all: (no parameters)
Search population: busca="população"
PNAD details: detalhes="pnad"
This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades).
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA/Pesquisas API. Returns a Markdown list.
Inputs: busca, detalhes. Returns: modo, busca, total, pesquisa, +3 more
ibge_sidraConsulta de tabelas SIDRAARead-onlyIdempotent
Queries SIDRA tables (IBGE's Automatic Recovery System).
SIDRA contains data from IBGE surveys like Census, PNAD, GDP, etc.
Common tables:
6579: Population estimates (annual)
9514: Census 2022 population
200: Census population (1970-2010)
4714: Population, territorial area and density (Census 2022)
4099: Unemployment rate (PNAD Contínua, quarterly)
5436: Average real income (PNAD Contínua, quarterly)
6706: GDP at current prices
5938: GDP per capita
Territorial levels:
1: Brazil
2: Region (North, Northeast, etc.)
3: State (UF)
6: Municipality
7: Metropolitan Region
Examples:
Brazil population 2023: tabela="6579", periodos="2023"
Population by state: tabela="6579", nivel_territorial="3"
Census 2022 by municipality: tabela="9514", nivel_territorial="6", localidades="3550308"
Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which municipality has the largest population?", "median GDP by state") use estatisticas=true — it computes min/max/mean/median/std-dev/labeled percentiles over ALL data rows BEFORE pagination and returns top/bottom rankings (default 10, cap 100 via topN), so one call answers what would otherwise require paging thousands of records. With agruparPor="" (e.g. "Unidade da Federação", "Ano") it ranks groups by descending sum, each with its own mini-distribution. Queries mixing several variables auto-group by "Variável" (units differ). SIDRA absence markers ("-", "..", "...", "X") are excluded from n. In this mode pagina/campos/formato are ignored and registros comes empty. Very large queries are refused by the source (since 2026-09-16 SIDRA tables are read through the Aggregates API, whose ceiling is lower than SIDRA's old 100,000-value cap: all municipalities × 12 yearly periods fails, × 8 works) — narrow periodos (e.g. "last 4") or raise nivel_territorial.
ibge_sidra is the low-level engine. Prefer a friendlier wrapper when it fits:
Census themes (1970–2022) → ibge_censo
Economic/social time series → ibge_indicadores
Rank/compare 2–10 localities → ibge_comparar
One municipality's panel → ibge_cidades Use ibge_sidra_tabelas and ibge_sidra_metadados to find a table code and its structure before querying.
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
Inputs: tabela (required), topN, campos, pagina, +8 more. Returns: nome, tabela, colunas, paginacao, +5 more
ibge_sidra_metadadosMetadados de tabela SIDRAARead-onlyIdempotent
Returns metadata for a specific SIDRA table.
Features:
General info (name, survey, subject, periodicity)
Available territorial levels
Variable list with units
Classifications and categories
Available periods
Use this tool to understand table structure BEFORE querying data with ibge_sidra.
Examples:
Population table metadata: tabela="6579"
Census 2022 metadata: tabela="9514"
PNAD unemployment: tabela="4714"
Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown.
Inputs: tabela (required), incluir_periodos, incluir_localidades. Returns: url, nome, codigo, assunto, +7 more
ibge_sidra_tabelasBusca de tabelas SIDRAARead-onlyIdempotent
Lists and searches available SIDRA tables.
Features:
List all SIDRA tables (aggregates)
Search by table name: every word must match (AND), accents and case ignored, and everyday Portuguese is resolved to the IBGE's own wording (renda→rendimento, desemprego→desocupação, cidade→município, gênero→sexo); when that happens the response says so in notas_vocabulario
Filter by survey (Census, PNAD, GDP, etc.)
Shows code and name of each table
SIDRA contains data from various surveys:
Demographic Census
PNAD Contínua (employment, income)
National Accounts (GDP)
Industrial Survey
Agricultural Survey
Examples:
List tables: (no parameters)
Search population tables: busca="população"
Census tables: pesquisa="censo"
This is step 1 of the SIDRA workflow: find a table code → ibge_sidra_metadados (structure) → ibge_sidra (query). For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades.
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns a Markdown table.
Inputs: busca, limite, pesquisa. Returns: busca, total, tabelas, pesquisa, +3 more
ibge_vizinhosMunicípios vizinhosARead-onlyIdempotent
Finds nearby/neighboring municipalities.
Features:
Search by IBGE code (7 digits) or municipality name
Without raio: returns municipalities that actually touch the reference municipality in the official municipal mesh
With raio: returns municipalities whose centroids fall within the requested radius in km
Optionally includes population data
Examples:
By code: municipio="3550308"
By name: municipio="Campinas", uf="SP"
With population: municipio="3550308", incluir_dados=true
Contiguity is topological (shared boundary); radius mode is an approximation based on centroid distance. For listing/searching municipalities, use ibge_municipios.
Behavior: read-only and idempotent — uses the public IBGE Localidades and Malhas v3 APIs; population enrichment, when requested, uses SIDRA. Returns a Markdown list.
Inputs: municipio (required), uf, raio, incluir_dados. Returns: total, vizinhos, municipio, provenance, +1 more
searchBusca para Deep ResearchARead-onlyIdempotent
Searches the IBGE (Brazilian official statistics: SIDRA tables, municipalities, known indicators) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).
This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools search and fetch. Pass one of the returned ids to fetch to read the document.
For direct questions and for data (values, series, rankings) prefer the ibge_* tools (ibge_sidra, ibge_cidades, ibge_indicadores, ibge_comparar…), which return the actual data with provenance — this is a catalog index, not a data query.
Query: natural language or keywords, Portuguese or English; accents and case are ignored.
Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.
Inputs: query (required). Returns: results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Most tools target distinct data surfaces, and the descriptions add explicit 'use a different tool when' guidance that resolves most potential confusion. However, there is genuine overlap among the locality tools (ibge_municipios, ibge_localidade, ibge_geocodigo) and among the SIDRA-family tools (ibge_sidra wrappers: ibge_censo, ibge_indicadores, ibge_datasaude, ibge_comparar, ibge_cidades), where an agent must lean heavily on prose to pick correctly.
Nearly all tools use a consistent snake_case 'ibge_<noun>' pattern (ibge_estados, ibge_sidra_tabelas, ibge_malhas_tema), which is highly predictable and scannable. The two bare 'search' and 'fetch' tools break the prefix convention, though that deviation is intentional for the Deep Research contract.
24 tools is on the heavy side and several are convenience wrappers over the same underlying SIDRA engine, so surface area is larger than strictly necessary. The breadth of the IBGE domain (geography, census, indicators, news, calendar, names, countries) partially justifies the count, placing it at borderline-heavy rather than excessive.
Coverage is broad and coherent: localities, geographic meshes, static maps, census themes, time-series indicators, health, news, calendar, names and international data are all present, with clear catalog/lookup entry points. As a fully read-only public-data API there is no write lifecycle to cover, so the main residual gap is the thin/overlapping wrapper layer rather than missing capabilities.
Maintenance
Related MCP Connectors
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
Discover, resolve, and query official Brazilian economic data with semantic search and provenance.
Banco Central do Brasil (BCB): SGS series, Focus expectations, PTAX, stats + provenance. 17 tools.
Brazilian public data API for AI agents. BCB, IBGE, CVM, B3, compliance. x402 payments on Base.
Related MCP Servers
- AlicenseAqualityBmaintenanceExposes official IBGE data as MCP tools, including Brazilian localities, SIDRA statistical aggregates, and population indicators.11MIT
- 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