ibge-br-mcp

Name: ibge-br-mcp
Author: SidneyBissoli

npm version npm downloads Tests Coverage License: MIT

MCP Server for IBGE (Brazilian Institute of Geography and Statistics) APIs. 🇧🇷 Leia em Português

This server implements the Model Context Protocol (MCP) to provide access to IBGE's public APIs, enabling AI assistants to query geographic, demographic, and statistical data from Brazil.

Features

23 specialized tools covering all major IBGE data domains
227 automated tests with 97%+ core coverage
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

Related MCP server: Brasil API MCP

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

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_populacao`	Real-time Brazilian population projection
`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)

External Data (BCB & Health)

Tool	Description
`bcb`	Central Bank data (SELIC, IPCA, exchange rates)
`datasaude`	Health indicators via IBGE/DataSUS

News & Calendar

Tool	Description
`ibge_noticias`	IBGE news and press releases
`ibge_calendario`	IBGE release and collection calendar

Installation

Prerequisites

Node.js 18.x or higher
npm or yarn

From npm (recommended)

npm install -g ibge-br-mcp

From source

# 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

Configuration

Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

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

Or if installed from source:

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

Claude Code

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

Tool Usage Examples

ibge_estados

List all Brazilian states.

# List all states ibge_estados # States in Northeast region ibge_estados(regiao="NE") # States sorted by abbreviation ibge_estados(ordenar="sigla")

ibge_municipios

List Brazilian municipalities.

# Municipalities of São Paulo state ibge_municipios(uf="SP") # Search municipalities by name ibge_municipios(busca="Campinas") # Municipalities in MG containing "Belo" ibge_municipios(uf="MG", busca="Belo")

ibge_cidades

Query municipal indicators (similar to Cidades@ portal).

# Panorama of São Paulo ibge_cidades(tipo="panorama", municipio="3550308") # Population history ibge_cidades(tipo="historico", municipio="3550308", indicador="populacao") # List available research ibge_cidades(tipo="pesquisas")

Available indicators: populacao, area, densidade, pib_per_capita, idh, escolarizacao, mortalidade, salario_medio, receitas, despesas

ibge_paises

Query international country data.

# List all countries ibge_paises(tipo="listar") # Brazil details ibge_paises(tipo="detalhes", pais="BR") # Search countries ibge_paises(tipo="buscar", busca="Argentina") # Countries in Americas ibge_paises(tipo="listar", regiao="americas")

Regions: americas, europa, africa, asia, oceania

ibge_sidra

Query SIDRA tables (IBGE's Automatic Recovery System).

# Brazil population in 2023 ibge_sidra(tabela="6579", periodos="2023") # Population by state ibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023") # Census 2022 for São Paulo municipality ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")

Common tables:

Code	Description
6579	Population estimates (annual)
9514	Census 2022 population
4714	Unemployment rate (PNAD)
6706	GDP at current prices

Territorial levels:

Code	Level
1	Brazil
2	Region (North, Northeast, etc.)
3	State (UF)
6	Municipality
7	Metropolitan Region
106	Health Region
127	Legal Amazon
128	Semi-arid

ibge_censo

Query Census data (1970-2022).

# Population Census 2022 ibge_censo(ano="2022", tema="populacao") # Historical population series ibge_censo(ano="todos", tema="populacao") # Literacy by state in 2010 ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")

Available themes: populacao, alfabetizacao, domicilios, idade_sexo, religiao, cor_raca, rendimento, migracao, educacao, trabalho

ibge_indicadores

Query economic and social indicators.

# GDP ibge_indicadores(indicador="pib") # IPCA last 12 months ibge_indicadores(indicador="ipca", periodos="last 12") # Unemployment by state ibge_indicadores(indicador="desemprego", nivel_territorial="3") # List all indicators ibge_indicadores(indicador="listar")

Available indicators:

Category	Indicators
Economic	pib, pib_variacao, pib_per_capita, industria, comercio, servicos
Prices	ipca, ipca_acumulado, inpc
Labor	desemprego, ocupacao, rendimento, informalidade
Population	populacao, densidade
Agriculture	agricultura, pecuaria

ibge_nomes

Query name frequency and rankings.

# Frequency of "Maria" ibge_nomes(tipo="frequencia", nomes="Maria") # Compare names ibge_nomes(tipo="frequencia", nomes="João,José,Pedro") # Ranking of names in 2000s ibge_nomes(tipo="ranking", decada=2000) # Female names ranking ibge_nomes(tipo="ranking", sexo="F")

ibge_malhas

Get geographic meshes (maps).

# Brazil with states ibge_malhas(localidade="BR", resolucao="2") # São Paulo with municipalities ibge_malhas(localidade="SP", resolucao="5") # Specific municipality ibge_malhas(localidade="3550308") # SVG format ibge_malhas(localidade="BR", formato="svg")

Resolution levels:

Value	Internal Divisions
0	No divisions (outline only)
2	States
5	Municipalities

bcb

Query Central Bank of Brazil data.

# SELIC last 12 months bcb(indicador="selic", ultimos=12) # IPCA for 2023 bcb(indicador="ipca", dataInicio="01/01/2023", dataFim="31/12/2023") # Dollar exchange rate last 30 days bcb(indicador="dolar_venda", ultimos=30)

Available indicators: selic, cdi, tr, ipca, ipca_acum, igpm, inpc, dolar_compra, dolar_venda, euro, desemprego

datasaude

Query health indicators via IBGE/DataSUS.

# Infant mortality in Brazil datasaude(indicador="mortalidade_infantil") # Life expectancy by state datasaude(indicador="esperanca_vida", nivel_territorial="3") # List indicators datasaude(indicador="listar")

Available indicators: mortalidade_infantil, esperanca_vida, nascidos_vivos, obitos, fecundidade, saneamento_agua, saneamento_esgoto, plano_saude

APIs Used

IBGE APIs

Localities: servicodados.ibge.gov.br/api/v1/localidades
Names: servicodados.ibge.gov.br/api/v2/censos/nomes
Aggregates/SIDRA: servicodados.ibge.gov.br/api/v3/agregados
SIDRA API: apisidra.ibge.gov.br/values
Meshes: servicodados.ibge.gov.br/api/v3/malhas
News: servicodados.ibge.gov.br/api/v3/noticias
Population: servicodados.ibge.gov.br/api/v1/projecoes/populacao
CNAE: servicodados.ibge.gov.br/api/v2/cnae
Calendar: servicodados.ibge.gov.br/api/v3/calendario
Countries: servicodados.ibge.gov.br/api/v1/paises
Research: servicodados.ibge.gov.br/api/v1/pesquisas

External APIs

Central Bank (BCB): api.bcb.gov.br/dados/serie/bcdata.sgs - Interest rates, exchange rates, inflation

Development

# Build npm run build # Watch mode npm run watch # Run tests npm test # Run tests in watch mode npm run test:watch # Lint npm run lint # Format npm run format # Test with MCP inspector npm run inspector

Project Structure

ibge-br-mcp/ ├── src/ │ ├── index.ts # Main MCP server │ ├── types.ts # TypeScript types │ ├── config.ts # Configuration and constants │ ├── cache.ts # Request caching system │ ├── retry.ts # Retry with exponential backoff │ ├── errors.ts # Standardized error handling │ ├── validation.ts # Input validation helpers │ ├── metrics.ts # Metrics and logging │ ├── utils/ │ │ └── formatters.ts # Formatting utilities │ └── tools/ │ ├── index.ts # Tool exports │ ├── estados.ts # ibge_estados │ ├── municipios.ts # ibge_municipios │ ├── localidade.ts # ibge_localidade │ ├── geocodigo.ts # ibge_geocodigo │ ├── censo.ts # ibge_censo │ ├── populacao.ts # ibge_populacao │ ├── sidra.ts # ibge_sidra │ ├── sidra-tabelas.ts # ibge_sidra_tabelas │ ├── sidra-metadados.ts# ibge_sidra_metadados │ ├── indicadores.ts # ibge_indicadores │ ├── cnae.ts # ibge_cnae │ ├── calendario.ts # ibge_calendario │ ├── comparar.ts # ibge_comparar │ ├── malhas.ts # ibge_malhas │ ├── malhas-tema.ts # ibge_malhas_tema │ ├── vizinhos.ts # ibge_vizinhos │ ├── bcb.ts # bcb │ ├── datasaude.ts # datasaude │ ├── pesquisas.ts # ibge_pesquisas │ ├── nomes.ts # ibge_nomes │ ├── noticias.ts # ibge_noticias │ ├── paises.ts # ibge_paises │ └── cidades.ts # ibge_cidades ├── tests/ # Test files ├── dist/ # Compiled files ├── package.json ├── tsconfig.json ├── vitest.config.ts └── README.md

Testing

The project includes a comprehensive test suite with 227 tests covering:

Validation functions
Retry mechanism
Formatting utilities
Error handling
Cache operations
Integration tests with mocks

npm test

Quality Assurance

This project maintains high code quality standards:

227 automated tests covering validation, caching, retry logic, formatting, and integrations
97%+ test coverage on core modules (cache, validation, errors, types)
ESLint for code linting with zero warnings
Prettier for consistent code formatting
TypeScript strict mode for type safety
Automated CI/CD via GitHub Actions

Run tests locally:

# Run all tests npm test # Run tests with coverage npm run test:coverage # Run linter npm run lint