ibge-br-mcp

Purpose

ibge-br-mcp is an MCP (Model Context Protocol) server designed to give AI assistants real-time access to geographic, demographic, economic, and health data from the official Brazilian IBGE API. When a user asks an LLM, "What was the population of Belo Horizonte in the 2022 census?", the model may give a plausible but potentially outdated and unsourced number from its training data; ibge-br-mcp lets the assistant query the official IBGE API in real time, returning the exact value along with its source table and reference period.

Main capabilities

• 23 tools: covering IBGE's main data domains, including 21 ibge_* data tools, plus search / fetch tools provided for ChatGPT Deep Research.
• Data provenance: since v3.3.0, every successful response includes a provenance block (portfolio contract v1.0), containing the six keys source, source_url, data_vintage, retrieved_at, citation, license, as well as attribution. Provenance information is output through three channels: structuredContent.provenance, br.com.sidneybissoli.ibge/provenance and .../attribution under _meta, and a compact text footer at the end of the Markdown.
• Reference resources and analysis prompts: provides an MCP catalog and ready-made templates.
• Automated tests: 565 automated tests, with 88% overall coverage and 92% tool coverage.
• Caching and retries: automatic caching with configurable TTL; retry mechanism with exponential backoff.
• Input validation and error handling: comprehensive parameter validation and standardized error handling, with suggestions.
• TypeScript support: strict typing.

Tool categories

• Places and geography
• Statistical data (SIDRA)
• Economic and social indicators
• Municipal data (Cidades@)
• International data
• Classifications
• Maps and geographic grids
• News and calendar
• ChatGPT Deep Research (search / fetch, the name is fixed by the OpenAI contract, with no ibge_ prefix)

How to use

Environment requirements

Node.js 22.x or later.

Install from npm (recommended)

Can be run via npx.

Remote endpoint (no installation required)

The server is also hosted on Streamable HTTP, with no key required:https://ibge.sidneybissoli.com/mcp

Suitable for any client that accepts a remote MCP server, such as claude.ai custom connectors, Claude Code, ChatGPT, Cursor, VS Code, etc.

Claude Desktop configuration

Add the configuration in claude_desktop_config.json.

ChatGPT (Deep Research)

ChatGPT Deep Research only uses MCP servers that expose search and fetch. Point the connector to the hosted endpoint; no key is required. search ranks queries against SIDRA tables, municipalities, and known indicators, returning { id, title, url }; fetch returns a readable Markdown document and the canonical public URL.

Use cases

• Query the list and codes of Brazilian states and municipalities.
• Query municipal indicators (population, area, density, GDP per capita, HDI, school enrollment rate, mortality rate, average salary, income, expenditure).
• Query international country data (Americas, Europe, Africa, Asia, Oceania).
• Query SIDRA tables (IBGE automatic recovery system).
• Query census data (1970-2022), with topics including population, literacy, households, age and sex, religion, race, income, migration, education, and work.
• Query economic and social indicators.
• Query name frequency and ranking.
• Get geographic grids (maps).
• Query Brazilian health indicators provided through IBGE SIDRA (some produced by DataSUS, such as mortality and births).
• Statistics mode: for maximum/minimum/mean/median/distribution/ranking questions, pass estatisticas=true, and the server calculates the full distribution before pagination and returns top/bottom rankings.

Limitations

• The IBGE API itself does not declare a license; the legal framework is the Brazilian open data framework (Lei 12.527/2011 and Decreto 8.777/2016), which allows unrestricted reuse and free use, with the only obligation being to cite the source.
• Statistics mode responses and ibge_comparar are marked as derived data, because aggregate values are calculated server-side from raw IBGE values.
• Each value is the version published by SIDRA at retrieved_at; IBGE revises published figures anddoes not retain earlier versions.
• The glossary contains only measured pairings; concepts that IBGE does not publish as aggregates (such as turismo, aposentadoria, frota) still return zero results.
• As of 2026-09-15, apisidra.ibge.gov.br is behind a browser-only Cloudflare challenge, and SIDRA tables are read through servicodados.ibge.gov.br/api/v3/agregados with view=flat.
• The project structure contains 565 tests covering validation, retries, formatting, caching, and integration.
• Quality assurance: ESLint zero warnings, Prettier, TypeScript strict mode, GitHub Actions CI/CD.
• Each release publishes in its MCP Registry entry the sha256 of the surface fingerprint it serves (initialize, tools, resources, prompts), as well as which methods can respond without credentials.