ibge-br-mcp

# IBGE Brasil MCP Server

[![npm version](https://img.shields.io/npm/v/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
[![npm downloads](https://img.shields.io/npm/dm/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
[![node](https://img.shields.io/node/v/ibge-br-mcp)](https://www.npmjs.com/package/ibge-br-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
[![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-ibge-br-mcp)](https://lobehub.com/mcp/sidneybissoli-ibge-br-mcp)
[![smithery badge](https://smithery.ai/badge/sidneybissoli/ibge-br-mcp)](https://smithery.ai/server/sidneybissoli/ibge-br-mcp)
[![ibge-br-mcp MCP server](https://glama.ai/mcp/servers/@SidneyBissoli/ibge-br-mcp/badges/score.svg)](https://glama.ai/mcp/servers/@SidneyBissoli/ibge-br-mcp)
[![CI](https://github.com/SidneyBissoli/ibge-br-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SidneyBissoli/ibge-br-mcp/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A588%25-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp/blob/main/vitest.config.ts)
[![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/ibge-br-mcp?style=flat&logo=github)](https://github.com/SidneyBissoli/ibge-br-mcp)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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](README.pt-BR.md)

This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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**](docs/demo.md) 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**](examples/README.md) 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](#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](docs/artigo-sidra-tabela-certa.pt-BR.md) — 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](https://sidneybissoli.com/en/blog/posts/sidra-tabela-certa/).

🔌 **Tutorial:** [Querying SIDRA through MCP in Claude and ChatGPT](https://sidneybissoli.com/en/blog/posts/sidra-via-mcp/) — 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](https://sidneybissoli.com/blog/posts/sidra-via-mcp/).

## Data provenance

Since v3.3.0 every successful tool response carries a **provenance block**
([portfolio contract v1.0](https://www.npmjs.com/package/@sbissoli/mcp-provenance)),
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` | Thematic meshes (biomes, Legal Amazon, semi-arid) |

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

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