Skip to main content
Glama

CensoSenso MCP

Version Node License: MIT CI

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

  1. Versão e estado

  2. Validação dos 645 municípios paulistas

  3. Arquitetura

  4. Ferramentas disponíveis

  5. Fluxo de uma chamada

  6. Algoritmos e regras de decisão

  7. Extração, cache e tolerância a falhas

  8. Procedência e auditabilidade

  9. SIDRA e estatísticas

  10. Geografia, vizinhança e recortes territoriais

  11. Pesquisa assistida search/fetch

  12. Validação, testes e gates

  13. Instalação local

  14. Uso remoto

  15. Desenvolvimento e reprodução

  16. Segurança, privacidade e limites operacionais

  17. Dados, licença e atribuições

  18. Status do protótipo e próximos passos


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:

  1. initialize;

  2. emissão/captura de mcp-session-id;

  3. notifications/initialized;

  4. tools/list;

  5. tools/call;

  6. consulta efetiva a fonte oficial;

  7. 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

a215de0ed21d5538db07a35e65c8dcd9fb1c201491c1ee1f4d0aaaa757810d86

O gate consulta:

https://servicodados.ibge.gov.br/api/v1/localidades/estados/35/municipios?orderBy=nome

O 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-645

Arquitetura

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 metodologia

Ferramentas 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

ibge_estados, ibge_municipios, ibge_localidade, ibge_geocodigo

SIDRA

ibge_sidra, ibge_sidra_tabelas, ibge_sidra_metadados, ibge_pesquisas

Censo e indicadores

ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades

Geografia

ibge_malhas, ibge_mapa, ibge_malhas_tema, ibge_vizinhos

Economia/classificações

ibge_cnae

Saúde e condições de vida

ibge_datasaude

Nomes

ibge_nomes

Países

ibge_paises

Informação corrente

ibge_noticias, ibge_calendario

Pesquisa assistida

search, fetch

Seleção recomendada

Pergunta

Ferramenta

Panorama de um município

ibge_cidades

Censo por tema

ibge_censo

Série econômica/social conhecida

ibge_indicadores

Comparar localidades

ibge_comparar

Consultar tabela SIDRA

ibge_sidra

Descobrir tabela

ibge_sidra_tabelas

Inspecionar dimensões/classificações

ibge_sidra_metadados

Resolver nome/código IBGE

ibge_geocodigo

Geometria administrativa

ibge_malhas

Mapa coroplético municipal

ibge_mapa

Vizinhança municipal

ibge_vizinhos

Recorte territorial especial

ibge_malhas_tema


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
35

sã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:

  1. verifica correspondência com UF;

  2. verifica correspondência com região;

  3. consulta municípios;

  4. restringe por UF, quando informada;

  5. usa busca textual por inclusão do nome;

  6. limita a 20 correspondências;

  7. se houver exatamente uma correspondência, retorna imediatamente a hierarquia detalhada;

  8. 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

STATIC

24 horas

MEDIUM

1 hora

SHORT

15 minutos

REALTIME

1 minuto

A chave de cache é construída com parâmetros:

  1. parâmetros undefined são removidos;

  2. nomes são ordenados lexicograficamente;

  3. 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_at continua 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, 504

També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:

  1. o código HTTP é preservado;

  2. o corpo textual é lido;

  3. páginas HTML de borda são descartadas;

  4. JSON de erro é inspecionado por message, mensagem, erro, error ou detail;

  5. espaços são normalizados;

  6. 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:

  1. structuredContent.provenance;

  2. structuredContent.attribution;

  3. _meta namespaced.

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_sidra

Wrappers 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:

-
..
...
X

Valores 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:

  1. correspondência exata sem diferença de caixa/acento;

  2. aliases conhecidos;

  3. correspondência parcial bidirecional;

  4. 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íguos

Neste modo, “vizinho” significa tocar a fronteira do município.

Com raio:

geometria
   ↓
centroid
   ↓
distance
   ↓
filtro por km

Esse 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_tema

Recortes 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:

  1. catálogo SIDRA;

  2. municípios;

  3. indicadores conhecidos;

  4. temas do Censo;

  5. indicadores de saúde;

  6. 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.

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:deploy

Encadeia:

  1. checagem do gerador de homologação;

  2. typecheck;

  3. lint;

  4. EOL;

  5. Prettier;

  6. build;

  7. suíte Vitest;

  8. cobertura;

  9. npm ci do Worker;

  10. typecheck do Worker;

  11. testes do Worker.

Gate dos 645 municípios

npm run gate:sp-645

Integração real

Em PowerShell:

.\scripts\run_integration_gate.ps1

Smoke

STDIO:

node scripts/smoke-mcp.mjs --stdio

Remoto:

node scripts/smoke-mcp.mjs https://censosenso.poderdapalavra.org

Baseline da superfície MCP

node scripts/dump-surface.mjs --stdio

Baseline atual:

baselines/surface-stdio-0.7.0.json

Mudanç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 ci

Build:

npm run build

Execução STDIO:

node dist/index.js

Ou:

npm start

Configuraçã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/mcp

O 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 dev

A equivalência funcional de uma reprodução exige, no mínimo:

  1. npm ci;

  2. npm run gate:deploy;

  3. negociação MCP via STDIO;

  4. negociação MCP via Worker;

  5. tools/list com superfície esperada;

  6. ao menos uma chamada real ao IBGE;

  7. procedência nos canais esperados;

  8. integridade dos snapshots;

  9. ausência de mudança inexplicada no baseline;

  10. resposta válida de /health, /status e /mcp.

CI/CD

Fluxo operacional:

push/merge
   ↓
GitHub
   ↓
gates
   ↓
Cloudflare Workers Build
   ↓
wrangler deploy
   ↓
health/status/MCP

Seguranç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 Found

Esse 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:

  1. publicar a árvore homologada completa neste repositório;

  2. executar novamente o gate completo na árvore pública;

  3. executar smoke remoto após a migração;

  4. criar tag/release pública;

  5. iniciar com um grupo externo reduzido;

  6. monitorar erros, uso e rate limiting;

  7. 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 tools
fetchDocumento para Deep ResearchA
Read-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çõesA
Read-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áficoA
Read-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@)A
Read-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 CNAEA
Read-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 localidadesA
Read-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údeA
Read-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 BrasilA
Read-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 IBGEA
Read-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 sociaisA
Read-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 localidadeA
Read-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áficasA
Read-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áticasA
Read-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 municipalA
Read-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 BrasilA
Read-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 nomesA
Read-onlyIdempotent

Queries name frequency and rankings in Brazil (IBGE).

Features:

  1. Name frequency (tipo='frequencia'):

    • Birth frequency by decade

    • Multiple names separated by comma

    • Filter by sex and locality

  2. 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 IBGEA
Read-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ísesA
Read-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 IBGEA
Read-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 SIDRAA
Read-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 SIDRAA
Read-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 SIDRAA
Read-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 vizinhosA
Read-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

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 24 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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