IBGE

This MCP server provides access to IBGE's public data through a standardized Model Context Protocol interface, enabling AI assistants to query geographic, demographic, and statistical information about Brazil. It offers a broad set of specialized tools, automatic caching, retry resilience, and strict input validation to help you build intelligent, data-driven conversations.

How to use

You run the MCP server locally and connect your MCP client to it. Use the available tools to retrieve Brazilian geographic data, census results, SIDRA tables, and related indicators. Each tool exposes a focused data domain (for example, ibge_estados for states, ibge_sidra for SIDRA tables, ibge_cidades for municipal indicators, and ibge_paises for country data). You can combine multiple tools in your workflows to answer complex questions about Brazil’s geography, demographics, and statistics. The server handles input validation, error messages with helpful suggestions, and caching to improve performance on repeated queries.

How to install

Prerequisites you need before installing:

1. Node.js 18.x or higher installed on your system.

2. npm or yarn available in your environment.

Choose one of the following installation methods.

From npm (recommended) install the MCP server globally so you can start it with a simple command.

npm install -g ibge-br-mcp

From source you can build and run the server locally for development or customization.

# Clone the repository
git clone https://github.com/SidneyBissoli/ibge-br-mcp.git
cd ibge-br-mcp

# Install dependencies
npm install

# Build the project
npm run build

Starting the MCP server with configuration examples

You can run the MCP server in two common ways. Use the one that matches how you prefer to start services on your machine. The following examples show the standard commands you would execute to start the MCP server locally.

# Start via NPX (local environment) using the package name
npx ibge-br-mcp

# Start from a built distribution with Node
node dist/index.js

Configuration and runtime connections

To integrate with Claude Desktop or Claude Code, you provide MCP server connection settings. The following configurations show how the server can be wired up as an MCP endpoint.

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

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

Security and maintenance notes

The server includes automatic request caching with configurable TTL and a retry mechanism with exponential backoff to handle transient network failures. Ensure your deployment environment follows your organization’s security practices, keeps dependencies up to date, and uses proper access controls for any hosted MCP endpoints.

Troubleshooting

If you encounter connection errors, verify that the MCP server process is running, that the correct command and arguments are used in your client configuration, and that your network allows access to the running server. Check the logs for validation errors, retry backoff messages, and any standardized error responses that provide guidance on correcting input parameters.

Notes

This MCP server exposes a wide range of IBGE data domains through clearly defined tools. You can query geographic data, demographic indicators, SIDRA tables, and more, all through a consistent MCP interface.

Available tools

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.

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.

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.

ibge_cidades

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

ibge_paises

Country data following UN M49 methodology.

ibge_populacao

Real-time Brazilian population projection.

ibge_nomes

Name frequency and rankings in Brazil.

ibge_malhas

Geographic meshes (maps).

ibge_malhas_tema

Thematic meshes (biomes, Legal Amazon, semi-arid).

bcb

Central Bank data (SELIC, IPCA, exchange rates).

datasaude

Health indicators via IBGE/DataSUS.

ibge_noticias

IBGE news and press releases.

ibge_calendario

IBGE release and collection calendar.

ibge_paises

International country data.

ibge_pesquisas

Research tables for IBGE datasets.