IBGE Brasil MCP Server

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:

1. 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.
2. _meta under br.com.sidneybissoli.ibge/provenance and .../attribution (out-of-band mirror for audit/UI, zero model tokens).
3. 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.

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
ibge_sidra_metadados	Get table metadata (variables, periods, levels)
ibge_pesquisas	List IBGE research surveys and their tables

Economic & Social Indicators

Tool	Description
ibge_indicadores	Economic and social indicators (GDP, IPCA, unemployment)
ibge_censo	Census data (1970-2022) with 16 themes
ibge_comparar	Compare indicators across localities with rankings

Municipal Data (Cidades@)

Tool	Description
ibge_cidades	Municipal indicators (population, HDI, GDP per capita, etc.)

International Data

Tool	Description
ibge_paises	Country data following UN M49 methodology

Demographics

Tool	Description
ibge_nomes	Name frequency and rankings in Brazil

Classifications

Tool	Description
ibge_cnae	CNAE (National Classification of Economic Activities)

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

Tool	Description
ibge_datasaude	Health indicators via IBGE's SIDRA

News & Calendar

Tool	Description
ibge_noticias	IBGE news and press releases
ibge_calendario	IBGE release and collection 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

You want…	Use
IPCA, INPC, GDP, unemployment (IBGE, primary source)	ibge_indicadores

Localities & codes