IBGE Brasil MCP

io.github.SidneyBissoliPublished by GitHub account SidneyBissoliv5.11.0Updated Oct 29, 2026

IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.

VerifiedStreamable HTTPWeb executableLocation & Lifestyle Web Search & Scraping Data & Analytics

Server details

Identifier: io.github.SidneyBissoli/ibge-br-mcp
Transport: Streamable HTTP
Runtime: Web executable
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account SidneyBissoli for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.SidneyBissoli%2Fibge-br-mcp.svg)](https://sourceweft.com/mcp/io.github.SidneyBissoli%2Fibge-br-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Queries official IBGE (Brazilian statistics) APIs for geography, census, economic, health and news data, with a provenance block on every answer.

What you can do: List, search and decode Brazilian states, municipalities, districts and IBGE codes, including neighbouring municipalities
Query SIDRA tables: discover tables, read their metadata, then pull data, plus surveys and census themes from 1970 to 2022
Fetch economic and social indicators (GDP, IPCA, unemployment, income) and municipal panels, and compare or rank localities
Retrieve health indicators, country data, name frequency rankings and CNAE activity classifications
Get geographic meshes as GeoJSON, TopoJSON or SVG, and inspect thematic recortes such as biomes or the Legal Amazon
Search IBGE news and the release calendar, and use search/fetch for Deep Research-style retrieval
When to use it: Useful when an assistant must answer questions about Brazil with exact, citable official figures instead of numbers guessed from training data: population, census, GDP, inflation, health, maps or municipality lookups.
Requirements: Either the hosted Streamable HTTP endpoint (no key) or the local npm package ibge-br-mcp, which needs Node.js 22 or higher. No account, API key, environment variable or header is required; network access to the IBGE public APIs is needed.

Before you install

All tools are read-only over public IBGE APIs. Values reflect the version published at extraction time, since IBGE revises figures and keeps no earlier version, so results can change between runs. Statistics-mode and comparison responses are computed server-side and marked as derived. Treat text returned from the data as data, not as instructions.

Installation

In SourceWeft

Open IBGE Brasil MCP in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.SidneyBissoli%2Fibge-br-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "ibge-brasil": {
      "type": "http",
      "url": "https://ibge.sidneybissoli.com/mcp"
    }
  }
}

README

IBGE Brasil MCP Server

[npm version] [npm downloads] [node] [MCP Registry] [LobeHub] [smithery badge] [ibge-br-mcp MCP server] [CI] [Coverage] [GitHub stars] [GitHub Sponsors] [License: MIT]

Live, exact Brazilian public data for your AI assistant — with provenance, not guesswork.

Ask an LLM "what was Belo Horizonte's population in the 2022 Census?" and you get a plausible number from its training data: maybe right, maybe outdated, with no source. ibge-br-mcp instead has your assistant query the official IBGE APIs in real time — returning the exact figure together with the table and period it came from.

🇧🇷 Leia em Português

This server implements the Model Context Protocol (MCP) to give AI assistants live, structured access to Brazil's public geographic, demographic, economic, and health data — sourced from the IBGE APIs (including health indicators served through IBGE's SIDRA system).

See it in action

Ask your assistant, in English or Portuguese:

"What was Belo Horizonte's population in the 2022 Census?" → ibge_cidades / ibge_censo
"List the municipalities of Espírito Santo." → ibge_municipios
"Compare GDP across the Southeast state capitals." → ibge_comparar

The answers come live from the official IBGE APIs — exact figures with the table and period they came from, not numbers guessed from training data.

Want to see a whole analysis rather than a single answer? The end-to-end demo works one real question — which state grew most between the 2010 and 2022 Censuses, and what drove it — from first call to conclusion, with every figure as it came back. The practical examples are seven shorter recipes, including ranking all 5,570 municipalities in a single call.

Features

23 tools covering all major IBGE data domains — 21 ibge_* data tools plus search/fetch for ChatGPT Deep Research
Provenance block on every response — source, canonical URL, reference period, real extraction timestamp, ready-to-use citation, and legal regime (see Data provenance)
Reference resources & analysis prompts (MCP catalogs + ready-made templates)
565 automated tests — 88% overall coverage, 92% across the tools
Automatic caching with configurable TTL for optimal performance
Retry mechanism with exponential backoff for network resilience
Comprehensive validation for all input parameters
Standardized error handling with helpful suggestions
Full TypeScript support with strict typing

📖 Article (in Portuguese): Como achar a tabela certa no SIDRA — e como saber que é a certa — finding the right SIDRA table, the metadata that settles it, a full worked example on 2022 Census data, and the four traps that cost the most. Also published on the site, in Portuguese and English: sidneybissoli.com.

🔌 Tutorial: Querying SIDRA through MCP in Claude and ChatGPT — how to connect this server in claude.ai, Claude Desktop, Claude Code, ChatGPT (developer mode and Deep Research), Cursor, VS Code and Gemini CLI, then one real query end to end with the provenance block it returns. Em português.

Data provenance

Since v3.3.0 every successful tool response carries a provenance block (portfolio contract v1.0), so each number is citable, auditable, and reproducible. The block is emitted on three channels:

structuredContent.provenance (parseable, visible to the model) — exactly six keys: source (the IBGE API queried), source_url (canonical URL that reproduces the query), data_vintage (reference period when the source exposes one; null otherwise), retrieved_at (the REAL upstream extraction instant, preserved across cache hits, Brasília time), citation ("Fonte: IBGE — [pesquisa/tabela], [URL], extraído em [data]."), and license — plus attribution, the canonical list of source URLs.
_meta under br.com.sidneybissoli.ibge/provenance and .../attribution (out-of-band mirror for audit/UI, zero model tokens).
A compact text footer appended to the Markdown, for text-only clients.

The IBGE APIs declare no license of their own; the legal regime is Brazil's open-data framework — Lei 12.527/2011 (LAI) and Decreto 8.777/2016 (unrestricted reuse, free use, obligation limited to crediting the source). Statistics-mode responses (estatisticas=true) and ibge_comparar are marked derived with an explanatory note in the canonical block, since the aggregates are computed server-side from the raw IBGE values.

What each number is, and which version of it. A SIDRA value says neither its period nor whether it is a monthly change, a year-to-date or 12-month accumulation, an index or a level — the record's period column and its Variável label do, and each ibge_indicadores entry is pinned to the one variable its name promises (since 5.7.0; before, nine of them mixed every variable of the table). data_vintage is ordered by the SIDRA period code, so a January–December request reads "janeiro 2024–dezembro 2024". Every value is the version SIDRA publishes at retrieved_at: IBGE revises published figures (quarterly GDP, PNAD reweighting, PIM/PMC/PMS) and keeps no earlier version.

Available Tools

Localities & Geography

Tool	Description
`ibge_estados`	List Brazilian states with region filtering
`ibge_municipios`	List municipalities by state or search by name
`ibge_localidade`	Get details of a locality by IBGE code
`ibge_geocodigo`	Decode IBGE codes or search codes by name
`ibge_vizinhos`	Find neighboring municipalities

Statistical Data (SIDRA)

Tool	Description
`ibge_sidra`	Query SIDRA tables (Census, PNAD, GDP, etc.)
`ibge_sidra_tabelas`	List and search available SIDRA tables (accent-insensitive; everyday Portuguese resolved to the IBGE's wording, and the response says so)
`ibge_sidra_metadados`	Get table metadata (variables, periods, levels)
`ibge_pesquisas`	List IBGE research surveys and their tables

Economic & Social Indicators

Municipal Data (Cidades@)

International Data

Demographics

Classifications

Maps & Geographic Meshes

Tool	Description
`ibge_malhas`	Geographic meshes (GeoJSON, TopoJSON, SVG)
`ibge_malhas_tema`	What a thematic recorte contains (biomes, Legal Amazon, semi-arid, coastal, border strip, metro regions, RIDEs) + the URL to download its geometry

Health

News & Calendar

ChatGPT Deep Research

Tool	Description
`search`	Searches the IBGE catalog (SIDRA tables, municipalities, known indicators) — OpenAI Deep Research contract
`fetch`	Returns one catalog document (table metadata, municipality hierarchy + population, indicator series) with its public URL for citation

The two are the only tools without the ibge_ prefix: their names are fixed by the OpenAI contract. For data queries keep using the ibge_* tools.

Which tool should I use?

With 23 tools, several can touch the same topic. Quick guide for the common overlaps:

Population & demographics

You want…	Use
A single municipality/state panel (population, HDI, GDP…)	`ibge_cidades`
Census data or historical series (1970–2022)	`ibge_censo`
Rank/compare 2–10 localities on one indicator	`ibge_comparar`
A macro indicator time series (GDP, IPCA, unemployment…)	`ibge_indicadores`
A specific SIDRA table / fine control	`ibge_sidra`
The largest/smallest/mean/median across a whole table	`ibge_sidra`/`ibge_censo`/`ibge_indicadores`/`ibge_datasaude` with `estatisticas=true`

Economic indicators

Localities & codes

You want…	Use
List/search municipalities	`ibge_municipios`
List states	`ibge_estados`
Resolve a name→code at any level, or decode a code's structure	`ibge_geocodigo`
Full record of one locality you already have the code for	`ibge_localidade`
Neighboring municipalities	`ibge_vizinhos`

SIDRA workflow

Discover → inspect → query: ibge_pesquisas / ibge_sidra_tabelas (find a table) → ibge_sidra_metadados (its structure) → ibge_sidra (query). For common data, the wrappers above (ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades) are usually easier.

Ask in your words, not the IBGE's

The IBGE names its tables in official statistical Portuguese, and ibge_sidra_tabelas matched your words against the table name as a plain substring, accents included — so populacao (no tilde, as anyone types it) returned nothing at all, and so did the everyday word for a concept the IBGE names differently. Measured over the 9,336 tables of the Aggregates API (2026-09-16), fixed since 5.1.0: both sides are normalised, every word must match (AND), and the everyday word is expanded to the IBGE's own — the response says so in notas_vocabulario, and zero results come with a way out.

you ask	hits before	the IBGE writes	hits
`populacao`, `ocupacao`, `instrucao`, `saude`, `area`, `agua`	0	população, ocupação, instrução, saúde, área, água	520, 364, 698, 518, 956, 256
`desemprego`	4	desocupação	33
`renda`	72	rendimento	1,126
`inflação`	0	IPCA, INPC, preços	37, 15, 75
`moradia`, `casa`	14, 101	domicílio	3,606
`cidade`	110	município	455
`natalidade`, `mortes`	0, 1	nascidos vivos, óbitos	84, 33
`gênero`	40	sexo	2,020
`negros`	0	cor ou raça	1,134
`universidade`, `faculdade`	0	ensino superior	12
`luz`, `fábrica`, `tabagismo`, `convênio`, `idosos`	0	energia elétrica, indústria, fumante, plano de saúde, 60 anos	43, 248, 94, 101, 89

Only measured pairs enter the table (src/vocabulario.ts, counts in the header): the word you ask with absent from the catalogue, the IBGE's word present. What the IBGE does not publish as an aggregate stays out and still returns zero — turismo, aposentadoria, frota — because an alias for data that does not exist promises what the source does not have. The same table feeds the Deep Research search index, which gets the everyday word as a keyword of the table whose name carries the IBGE's word.

Maps (meshes)

You want…	Use
Administrative outlines (Brazil/region/state/municipality)	`ibge_malhas`
Thematic areas (biomes, Legal Amazon, semi-arid, metro regions)	`ibge_malhas_tema` (IBGE Geosserviços WFS — the Malhas API does not publish these)

Installation

Prerequisites

Node.js 22.x or higher (engines.node)
npm or yarn

From npm (recommended)

From source

bash

# Clone the repositorygit clone https://github.com/SidneyBissoli/ibge-br-mcp.gitcd ibge-br-mcp
# Install dependenciesnpm install
# Build the projectnpm run build

# Clone the repositorygit clone https://github.com/SidneyBissoli/ibge-br-mcp.gitcd ibge-br-mcp
# Install dependenciesnpm install
# Build the projectnpm run build

Configuration

Remote endpoint (nothing to install)

The server is also hosted, with the same tools, over Streamable HTTP and without a key:

It works with any client that accepts a remote MCP server — a custom connector in claude.ai (Settings → Connectors → Add custom connector), claude mcp add --transport http ibge https://ibge.sidneybissoli.com/mcp in Claude Code, an app in ChatGPT, the mcp.json of Cursor and VS Code. The step-by-step for each client is in the tutorial. The sections below cover the local form, via npx.

Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

json

{  "mcpServers": {    "ibge-br-mcp": {      "command": "npx",      "args": ["-y", "ibge-br-mcp"]    }  }}

{  "mcpServers": {    "ibge-br-mcp": {      "command": "npx",      "args": ["-y", "ibge-br-mcp"]    }  }}

Or if installed from source:

json

{  "mcpServers": {    "ibge-br-mcp": {      "command": "node",      "args": ["/path/to/ibge-br-mcp/dist/index.js"]    }  }}

{  "mcpServers": {    "ibge-br-mcp": {      "command": "node",      "args": ["/path/to/ibge-br-mcp/dist/index.js"]    }  }}

Claude Code

json

{  "mcpServers": {    "ibge-br-mcp": {      "command": "npx",      "args": ["-y", "ibge-br-mcp"]    }  }}

{  "mcpServers": {    "ibge-br-mcp": {      "command": "npx",      "args": ["-y", "ibge-br-mcp"]    }  }}

ChatGPT (Deep Research)

ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the ibge_* tools. Point the connector at the hosted endpoint, no key required:

search ranks the query against SIDRA tables, municipalities and the known indicators and returns { id, title, url }; fetch returns the document as readable Markdown with the canonical public URL (sidra.ibge.gov.br or cidades.ibge.gov.br), which is what ChatGPT cites. Both carry the same provenance block as every other tool. In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the ibge_* tools remain the ones to use for data.

Tool Usage Examples

ibge_estados

List all Brazilian states.

# List all statesibge_estados
# States in Northeast regionibge_estados(regiao="NE")
# States sorted by abbreviationibge_estados(ordenar="sigla")

# List all statesibge_estados
# States in Northeast regionibge_estados(regiao="NE")
# States sorted by abbreviationibge_estados(ordenar="sigla")

ibge_municipios

List Brazilian municipalities.

# Municipalities of São Paulo stateibge_municipios(uf="SP")
# Search municipalities by nameibge_municipios(busca="Campinas")
# Municipalities in MG containing "Belo"ibge_municipios(uf="MG", busca="Belo")

# Municipalities of São Paulo stateibge_municipios(uf="SP")
# Search municipalities by nameibge_municipios(busca="Campinas")
# Municipalities in MG containing "Belo"ibge_municipios(uf="MG", busca="Belo")

ibge_cidades

Query municipal indicators (similar to Cidades@ portal).

# Panorama of São Pauloibge_cidades(tipo="panorama", municipio="3550308")
# Population historyibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")
# List available researchibge_cidades(tipo="pesquisas")

# Panorama of São Pauloibge_cidades(tipo="panorama", municipio="3550308")
# Population historyibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")
# List available researchibge_cidades(tipo="pesquisas")

Available indicators: populacao, area, densidade, pib_per_capita, idh, escolarizacao, mortalidade, salario_medio, receitas, despesas

ibge_paises

Query international country data.

# List all countriesibge_paises(tipo="listar")
# Brazil detailsibge_paises(tipo="detalhes", pais="BR")
# Search countriesibge_paises(tipo="buscar", busca="Argentina")
# Countries in Americasibge_paises(tipo="listar", regiao="americas")

# List all countriesibge_paises(tipo="listar")
# Brazil detailsibge_paises(tipo="detalhes", pais="BR")
# Search countriesibge_paises(tipo="buscar", busca="Argentina")
# Countries in Americasibge_paises(tipo="listar", regiao="americas")

Regions: americas, europa, africa, asia, oceania

ibge_sidra

Query SIDRA tables (IBGE's Automatic Recovery System).

# Brazil population in 2023ibge_sidra(tabela="6579", periodos="2023")
# Population by stateibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")
# Census 2022 for São Paulo municipalityibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")

# Brazil population in 2023ibge_sidra(tabela="6579", periodos="2023")
# Population by stateibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")
# Census 2022 for São Paulo municipalityibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")

Common tables:

Code	Description
6579	Population estimates (annual)
9514	Census 2022 population
4714	Population, territorial area and density (Census 2022)
4099	Unemployment rate (PNAD Contínua, quarterly)
1846	Quarterly GDP at current prices (Brazil)
5938	Municipal GDP at current prices (annual)
6784	Annual GDP and GDP per capita (Brazil)

Territorial levels:

Statistics mode (also on ibge_censo, ibge_indicadores, ibge_datasaude): for largest/smallest/mean/median/distribution/ranking questions, pass estatisticas=true — the server computes the full distribution (min/max/mean/ median/std-dev/labeled percentiles) over all rows before pagination and returns top/bottom rankings (topN, default 10). agruparPor="<column label>" ranks groups by descending sum, each with its own mini-distribution.

# Which state has the largest estimated population?ibge_sidra(tabela="6579", nivel_territorial="3", estatisticas=true)
# Census 2022 population distribution grouped by stateibge_censo(ano="2022", tema="populacao", nivel_territorial="3", estatisticas=true, agruparPor="Unidade da Federação")

# Which state has the largest estimated population?ibge_sidra(tabela="6579", nivel_territorial="3", estatisticas=true)
# Census 2022 population distribution grouped by stateibge_censo(ano="2022", tema="populacao", nivel_territorial="3", estatisticas=true, agruparPor="Unidade da Federação")

ibge_censo

Query Census data (1970-2022).

# Population Census 2022ibge_censo(ano="2022", tema="populacao")
# Historical population seriesibge_censo(ano="todos", tema="populacao")
# Literacy by state in 2010ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")

# Population Census 2022ibge_censo(ano="2022", tema="populacao")
# Historical population seriesibge_censo(ano="todos", tema="populacao")
# Literacy by state in 2010ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")

Available themes: populacao, alfabetizacao, domicilios, idade_sexo, religiao, cor_raca, rendimento, migracao, educacao, trabalho

ibge_indicadores

Query economic and social indicators.

# GDPibge_indicadores(indicador="pib")
# IPCA last 12 monthsibge_indicadores(indicador="ipca", periodos="last 12")
# Unemployment by stateibge_indicadores(indicador="desemprego", nivel_territorial="3")
# List all indicatorsibge_indicadores(indicador="listar")

# GDPibge_indicadores(indicador="pib")
# IPCA last 12 monthsibge_indicadores(indicador="ipca", periodos="last 12")
# Unemployment by stateibge_indicadores(indicador="desemprego", nivel_territorial="3")
# List all indicatorsibge_indicadores(indicador="listar")

Available indicators:

Category	Indicators
Economic	pib, pib_variacao, pib_per_capita, industria, comercio, servicos
Prices	ipca, ipca_acumulado, inpc
Labor	desemprego, ocupacao, rendimento, informalidade
Population	populacao, densidade
Agriculture	agricultura, pecuaria

ibge_nomes

Query name frequency and rankings.

# Frequency of "Maria"ibge_nomes(tipo="frequencia", nomes="Maria")
# Compare namesibge_nomes(tipo="frequencia", nomes="João,José,Pedro")
# Ranking of names in 2000sibge_nomes(tipo="ranking", decada=2000)
# Female names rankingibge_nomes(tipo="ranking", sexo="F")

# Frequency of "Maria"ibge_nomes(tipo="frequencia", nomes="Maria")
# Compare namesibge_nomes(tipo="frequencia", nomes="João,José,Pedro")
# Ranking of names in 2000sibge_nomes(tipo="ranking", decada=2000)
# Female names rankingibge_nomes(tipo="ranking", sexo="F")

ibge_malhas

Get geographic meshes (maps).

# Brazil with statesibge_malhas(localidade="BR", resolucao="2")
# São Paulo with municipalitiesibge_malhas(localidade="SP", resolucao="5")
# Specific municipalityibge_malhas(localidade="3550308")
# SVG formatibge_malhas(localidade="BR", formato="svg")

# Brazil with statesibge_malhas(localidade="BR", resolucao="2")
# São Paulo with municipalitiesibge_malhas(localidade="SP", resolucao="5")
# Specific municipalityibge_malhas(localidade="3550308")
# SVG formatibge_malhas(localidade="BR", formato="svg")

Resolution levels:

ibge_datasaude

Query Brazilian health indicators served through IBGE's SIDRA (some originally produced by DataSUS, e.g. mortality and births).

# Infant mortality in Brazilibge_datasaude(indicador="mortalidade_infantil")
# Life expectancy by stateibge_datasaude(indicador="esperanca_vida", nivel_territorial="3")
# List indicatorsibge_datasaude(indicador="listar")

# Infant mortality in Brazilibge_datasaude(indicador="mortalidade_infantil")
# Life expectancy by stateibge_datasaude(indicador="esperanca_vida", nivel_territorial="3")
# List indicatorsibge_datasaude(indicador="listar")

Available indicators: mortalidade_infantil, esperanca_vida, nascidos_vivos, obitos, fecundidade, saneamento_agua, saneamento_esgoto, plano_saude

APIs Used

IBGE APIs

Localities: servicodados.ibge.gov.br/api/v1/localidades
Names: servicodados.ibge.gov.br/api/v2/censos/nomes
Aggregates/SIDRA: servicodados.ibge.gov.br/api/v3/agregados (SIDRA tables are read here with view=flat; apisidra.ibge.gov.br has been behind a browser-only Cloudflare challenge since 2026-09-15)
Meshes: servicodados.ibge.gov.br/api/v3/malhas
News: servicodados.ibge.gov.br/api/v3/noticias
Population: servicodados.ibge.gov.br/api/v1/projecoes/populacao
CNAE: servicodados.ibge.gov.br/api/v2/cnae
Calendar: servicodados.ibge.gov.br/api/v3/calendario
Countries: servicodados.ibge.gov.br/api/v1/paises
Research: servicodados.ibge.gov.br/api/v1/pesquisas

Development

bash

# Buildnpm run build
# Watch modenpm run watch
# Run testsnpm test
# Run tests in watch modenpm run test:watch
# Lintnpm run lint
# Formatnpm run format
# Test with MCP inspectornpm run inspector

# Buildnpm run build
# Watch modenpm run watch
# Run testsnpm test
# Run tests in watch modenpm run test:watch
# Lintnpm run lint
# Formatnpm run format
# Test with MCP inspectornpm run inspector

Project Structure

ibge-br-mcp/├── src/│   ├── index.ts              # Main MCP server│   ├── types.ts              # TypeScript types│   ├── config.ts             # Configuration and constants│   ├── cache.ts              # Request caching system│   ├── retry.ts              # Trip to the source over @sbissoli/mcp-upstream (retry, timeout, budget, retrieval count)│   ├── errors.ts             # Standardized error handling│   ├── validation.ts         # Input validation helpers│   ├── metrics.ts            # Metrics and logging│   ├── utils/│   │   └── formatters.ts     # Formatting utilities│   └── tools/│       ├── index.ts          # Tool exports│       ├── estados.ts        # ibge_estados│       ├── municipios.ts     # ibge_municipios│       ├── localidade.ts     # ibge_localidade│       ├── geocodigo.ts      # ibge_geocodigo│       ├── censo.ts          # ibge_censo│       ├── sidra.ts          # ibge_sidra│       ├── sidra-tabelas.ts  # ibge_sidra_tabelas│       ├── sidra-metadados.ts# ibge_sidra_metadados│       ├── indicadores.ts    # ibge_indicadores│       ├── cnae.ts           # ibge_cnae│       ├── calendario.ts     # ibge_calendario│       ├── comparar.ts       # ibge_comparar│       ├── malhas.ts         # ibge_malhas│       ├── malhas-tema.ts    # ibge_malhas_tema│       ├── vizinhos.ts       # ibge_vizinhos│       ├── datasaude.ts      # ibge_datasaude│       ├── pesquisas.ts      # ibge_pesquisas│       ├── nomes.ts          # ibge_nomes│       ├── noticias.ts       # ibge_noticias│       ├── paises.ts         # ibge_paises│       └── cidades.ts        # ibge_cidades├── tests/                    # Test files├── dist/                     # Compiled files├── package.json├── tsconfig.json├── vitest.config.ts└── README.md

ibge-br-mcp/├── src/│   ├── index.ts              # Main MCP server│   ├── types.ts              # TypeScript types│   ├── config.ts             # Configuration and constants│   ├── cache.ts              # Request caching system│   ├── retry.ts              # Trip to the source over @sbissoli/mcp-upstream (retry, timeout, budget, retrieval count)│   ├── errors.ts             # Standardized error handling│   ├── validation.ts         # Input validation helpers│   ├── metrics.ts            # Metrics and logging│   ├── utils/│   │   └── formatters.ts     # Formatting utilities│   └── tools/│       ├── index.ts          # Tool exports│       ├── estados.ts        # ibge_estados│       ├── municipios.ts     # ibge_municipios│       ├── localidade.ts     # ibge_localidade│       ├── geocodigo.ts      # ibge_geocodigo│       ├── censo.ts          # ibge_censo│       ├── sidra.ts          # ibge_sidra│       ├── sidra-tabelas.ts  # ibge_sidra_tabelas│       ├── sidra-metadados.ts# ibge_sidra_metadados│       ├── indicadores.ts    # ibge_indicadores│       ├── cnae.ts           # ibge_cnae│       ├── calendario.ts     # ibge_calendario│       ├── comparar.ts       # ibge_comparar│       ├── malhas.ts         # ibge_malhas│       ├── malhas-tema.ts    # ibge_malhas_tema│       ├── vizinhos.ts       # ibge_vizinhos│       ├── datasaude.ts      # ibge_datasaude│       ├── pesquisas.ts      # ibge_pesquisas│       ├── nomes.ts          # ibge_nomes│       ├── noticias.ts       # ibge_noticias│       ├── paises.ts         # ibge_paises│       └── cidades.ts        # ibge_cidades├── tests/                    # Test files├── dist/                     # Compiled files├── package.json├── tsconfig.json├── vitest.config.ts└── README.md

Testing

The project includes a comprehensive test suite with 565 tests covering:

Validation functions
Retry mechanism
Formatting utilities
Error handling
Cache operations
Integration tests with mocks

Quality Assurance

This project maintains high code quality standards:

565 automated tests covering validation, caching, retry logic, formatting, and integrations
88% overall test coverage — cache and validation modules above 97%
ESLint for code linting with zero warnings
Prettier for consistent code formatting
TypeScript strict mode for type safety
Automated CI/CD via GitHub Actions

Run tests locally:

Surface fingerprint, checkable from the registry

Every release publishes, in its MCP Registry entry, the sha256 of the surface this version serves (initialize, tools, resources, prompts) and which methods answer without a credential. A surface change without a version bump fails the build; the fingerprint in the registry lets a client check the same thing on its own side. Canonical form and procedure: SPEC.md of @sbissoli/mcp-surface. To check it yourself (Node 18+, no dependencies):

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjsnode verify.mjs io.github.SidneyBissoli/ibge-br-mcp

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjsnode verify.mjs io.github.SidneyBissoli/ibge-br-mcp

License

MIT

Author

Sidney da Silva Pereira Bissoli

References

Source: README.md at commit 9579ed9

Tools

ibge_estados

Estados do Brasil

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.

Parametersregiaoordenar

ibge_municipios

Municípios do Brasil

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.

Parametersufbuscalimite

ibge_localidade

Detalhes de localidade

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.

Parameterstipocodigorequired

ibge_sidra

Consulta de tabelas SIDRA

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) - 1846: Quarterly GDP at current prices (Brazil) - 5938: Municipal GDP at current prices (annual, down to municipality) - 6784: Annual GDP and GDP per capita (Brazil) 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" What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps no earlier version. 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 wh

ParameterstopNcampospaginatabelarequiredformatoperiodosvariaveisagruparPorlocalidadesestatisticasclassificacoesnivel_territorial

ibge_nomes

Frequência e ranking de nomes

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.

Parameterssexotiporequirednomesdecadalimitelocalidade

ibge_noticias

Notícias do IBGE

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.

Parametersdeatetipobuscapaginadestaquequantidade

ibge_sidra_tabelas

Busca de tabelas SIDRA

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.

Parametersbuscalimitepesquisa

ibge_sidra_metadados

Metadados de tabela SIDRA

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.

Parameterstabelarequiredincluir_periodosincluir_localidades

ibge_malhas

Malhas geográficas

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) 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. Returns the mesh in the requested format (GeoJSON, TopoJSON, or SVG).

Parameterstipoformatoqualidaderesolucaolocalidaderequiredintrarregiao

ibge_pesquisas

Pesquisas do IBGE

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.

Parametersbuscadetalhes

ibge_censo

Censo Demográfico

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="<column label>" 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 - 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.

ParametersanotematopNcamposformatoagruparPorlocalidadesestatisticasnivel_territorial

ibge_indicadores

Indicadores econômicos e sociais

Queries IBGE economic and social indicators. Available indicators: **Economic:** - pib: quarterly GDP at current prices, R$ million (Brazil only) - pib_variacao: quarterly GDP volume change, % over the same quarter of the previous year (Brazil only) - pib_per_capita: annual GDP per capita at current prices, R$ (Brazil only) - industria: industrial production index, general industry (2022=100) - comercio: retail sales volume index (2022=100) - servicos: services volume index (2022=100, Brazil only) **Prices:** - ipca: IPCA monthly change, % - ipca_acumulado: IPCA accumulated over 12 months, % - inpc: INPC monthly change, % **Labor:** - desemprego: Unemployment rate - ocupacao: Employed people (thousands) - rendimento: average real income from all jobs, R$ — each period is a ROLLING quarter (e.g. "jun-jul-ago 2026"), Brazil only - 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" Each indicator returns ONE variable — the one its name says; for another one of the same table (e.g. the year-to-date change) use ibge_sidra with variaveis. What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps

ParameterstopNcamposformatoperiodoscategoriaindicadoragruparPorlocalidadesestatisticasnivel_territorial

ibge_cnae

Classificação CNAE

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.

Parametersbuscanivelcodigolimite

ibge_geocodigo

Códigos geográficos do IBGE

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.

Parametersufnomecodigo

ibge_calendario

Calendário de divulgações

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.

Parametersdeatetipopaginaprodutoquantidade

ibge_comparar

Comparação entre localidades

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

Parametersformatoindicadorlocalidadesrequired

ibge_malhas_tema

Malhas temáticas

Lists what a THEMATIC territorial recorte of Brazil contains: how many features, with which codes and names, and the URL to download its geometry. 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`: only the recortes that have a per-feature code accept it — biomas (the biome code) and the two municipality ones, costeiro and fronteira (the 7-digit IBGE municipality code). Ask without `codigo` to see what exists; biome codes come from the source, not from a fixed table. GEOMETRY IS NOT IN THE RESPONSE, on purpose: one biome polygon alone is over 9 MB. The response carries the attributes plus a canonical WFS URL that returns the recorte with geometry in GeoJSON. Use a different tool when: - Administrative meshes WITH geometry (country/region/state/municipality outlines) → ibge_malhas Behavior: read-only and idempotent — a live GET against the public IBGE Geosserviços WFS (IBGE Geociências), which is a different service from the Malhas API and the only one that publishes these recortes. Returns Markdown plus a typed structuredContent payload.

Parameterstemarequiredcodigolimite

ibge_vizinhos

Municípios vizinhos

Finds nearby/neighboring municipalities. Features: - Search by IBGE code (7 digits) or municipality name - Returns municipalities in the same mesoregion (proximity approximation) - Optionally includes population data Note: Uses mesoregion as geographic proximity proxy. For exact spatial neighborhood, mesh processing would be required. Examples: - By code: municipio="3550308" - By name: municipio="Campinas", uf="SP" - With population: municipio="3550308", incluir_dados=true Note: proximity is approximated by shared mesoregion (not exact spatial adjacency). For listing/searching municipalities, use ibge_municipios. Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown list.

Parametersufraiomunicipiorequiredincluir_dados

ibge_datasaude

Indicadores de saúde

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 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="<column label>" 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.

ParameterstopNcamposformatoperiodoindicadorrequiredagruparPorlocalidadeestatisticasnivel_territorial

ibge_paises

Dados de países

Queries international country data via IBGE. Features: - List all countries (following UN M49 methodology) - Country details (area, languages, currency, location) with the latest published value of country indicators — by default population, GDP, GDP per capita, HDI and life expectancy - Pick other indicators with indicadores="<ids or aliases separated by |>" - Indicator catalog as published by IBGE (34 indicators: economy, population, health, environment, networks), with unit and scale - Search countries by name - Filter by region/continent Each indicator value is the most recent one the source publishes for that country, with its year or period (some are 3- or 5-year ranges like "2021-2023"), as text (it can be "<2.5"), plus unit and scale (multiplicador) — null when the source has none. 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" - Chosen indicators: tipo="detalhes", pais="AR", indicadores="idh|77852" - Search: tipo="buscar", busca="Argentina" - Americas countries: tipo="listar", regiao="americas" - Indicator catalog: tipo="indicadores" Behavior: read-only and idempotent — a live GET against the public IBGE Países API. Returns Markdown.

Parameterspaistipobuscaregiaoindicadores

ibge_cidades

Panorama municipal (Cidades@)

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 — a live GET against the public IBGE APIs (Cidades@/agregados). Returns Markdown plus a typed structuredContent payload.

Parametersuftipopesquisaindicadormunicipio

search

Busca para Deep Research

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.

Parametersqueryrequired

fetch

Documento para Deep Research

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.

Parametersidrequired

Version history

v5.11.0LatestOct 29, 2026
v5.10.0Oct 16, 2026
v5.8.1Oct 9, 2026
v5.7.0Oct 8, 2026
v5.6.2Oct 8, 2026
v5.6.1Oct 7, 2026
v5.6.0Oct 6, 2026
v5.5.1Oct 2, 2026
v5.4.0Sep 27, 2026
v5.3.0Sep 25, 2026
v5.2.0Sep 22, 2026
v5.1.2Sep 22, 2026
v5.1.1Sep 17, 2026
v5.0.1Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 daysRequired25 pts
Auth declaredRequired10 pts
Tools listedRequired15 pts
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts

Value	Internal Divisions
0	No divisions (outline only)
2	States
5	Municipalities