SidneyBissoli/ibge-br-mcp

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