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. - 23 specialized tools covering all major IBGE data domains - 227 automated tests with 97%+ core coverage - Autom
Add this skill
npx mdskills install SidneyBissoli/ibge-br-mcpComprehensive MCP server with 23 well-documented tools for Brazilian geographic and statistical data
1# ibge-br-mcp23[](https://www.npmjs.com/package/ibge-br-mcp)4[](https://www.npmjs.com/package/ibge-br-mcp)5[](https://github.com/SidneyBissoli/ibge-br-mcp)6[](https://github.com/SidneyBissoli/ibge-br-mcp)7[](https://opensource.org/licenses/MIT)8[](https://smithery.ai/server/sidneybissoli/ibge-br-mcp)910MCP Server for IBGE (Brazilian Institute of Geography and Statistics) APIs.11🇧🇷 [Leia em Português](README.pt-BR.md)1213This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to provide access to IBGE's public APIs, enabling AI assistants to query geographic, demographic, and statistical data from Brazil.1415## Features1617- **23 specialized tools** covering all major IBGE data domains18- **227 automated tests** with 97%+ core coverage19- **Automatic caching** with configurable TTL for optimal performance20- **Retry mechanism** with exponential backoff for network resilience21- **Comprehensive validation** for all input parameters22- **Standardized error handling** with helpful suggestions23- **Full TypeScript support** with strict typing2425## Available Tools2627### Localities & Geography28| Tool | Description |29|:-----|:------------|30| `ibge_estados` | List Brazilian states with region filtering |31| `ibge_municipios` | List municipalities by state or search by name |32| `ibge_localidade` | Get details of a locality by IBGE code |33| `ibge_geocodigo` | Decode IBGE codes or search codes by name |34| `ibge_vizinhos` | Find neighboring municipalities |3536### Statistical Data (SIDRA)37| Tool | Description |38|:-----|:------------|39| `ibge_sidra` | Query SIDRA tables (Census, PNAD, GDP, etc.) |40| `ibge_sidra_tabelas` | List and search available SIDRA tables |41| `ibge_sidra_metadados` | Get table metadata (variables, periods, levels) |42| `ibge_pesquisas` | List IBGE research surveys and their tables |4344### Economic & Social Indicators45| Tool | Description |46|:-----|:------------|47| `ibge_indicadores` | Economic and social indicators (GDP, IPCA, unemployment) |48| `ibge_censo` | Census data (1970-2022) with 16 themes |49| `ibge_comparar` | Compare indicators across localities with rankings |5051### Municipal Data (Cidades@)52| Tool | Description |53|:-----|:------------|54| `ibge_cidades` | Municipal indicators (population, HDI, GDP per capita, etc.) |5556### International Data57| Tool | Description |58|:-----|:------------|59| `ibge_paises` | Country data following UN M49 methodology |6061### Demographics62| Tool | Description |63|:-----|:------------|64| `ibge_populacao` | Real-time Brazilian population projection |65| `ibge_nomes` | Name frequency and rankings in Brazil |6667### Classifications68| Tool | Description |69|:-----|:------------|70| `ibge_cnae` | CNAE (National Classification of Economic Activities) |7172### Maps & Geographic Meshes73| Tool | Description |74|:-----|:------------|75| `ibge_malhas` | Geographic meshes (GeoJSON, TopoJSON, SVG) |76| `ibge_malhas_tema` | Thematic meshes (biomes, Legal Amazon, semi-arid) |7778### External Data (BCB & Health)79| Tool | Description |80|:-----|:------------|81| `bcb` | Central Bank data (SELIC, IPCA, exchange rates) |82| `datasaude` | Health indicators via IBGE/DataSUS |8384### News & Calendar85| Tool | Description |86|:-----|:------------|87| `ibge_noticias` | IBGE news and press releases |88| `ibge_calendario` | IBGE release and collection calendar |8990## Installation9192### Prerequisites9394- Node.js 18.x or higher95- npm or yarn9697### From npm (recommended)9899```bash100npm install -g ibge-br-mcp101```102103### From source104105```bash106# Clone the repository107git clone https://github.com/SidneyBissoli/ibge-br-mcp.git108cd ibge-br-mcp109110# Install dependencies111npm install112113# Build the project114npm run build115```116117## Configuration118119### Claude Desktop120121Add to your Claude Desktop configuration file (`claude_desktop_config.json`):122123```json124{125 "mcpServers": {126 "ibge-br-mcp": {127 "command": "npx",128 "args": ["ibge-br-mcp"]129 }130 }131}132```133134Or if installed from source:135136```json137{138 "mcpServers": {139 "ibge-br-mcp": {140 "command": "node",141 "args": ["/path/to/ibge-br-mcp/dist/index.js"]142 }143 }144}145```146147### Claude Code148149```json150{151 "mcpServers": {152 "ibge-br-mcp": {153 "command": "npx",154 "args": ["ibge-br-mcp"]155 }156 }157}158```159160## Tool Usage Examples161162### ibge_estados163164List all Brazilian states.165166```167# List all states168ibge_estados169170# States in Northeast region171ibge_estados(regiao="NE")172173# States sorted by abbreviation174ibge_estados(ordenar="sigla")175```176177### ibge_municipios178179List Brazilian municipalities.180181```182# Municipalities of São Paulo state183ibge_municipios(uf="SP")184185# Search municipalities by name186ibge_municipios(busca="Campinas")187188# Municipalities in MG containing "Belo"189ibge_municipios(uf="MG", busca="Belo")190```191192### ibge_cidades193194Query municipal indicators (similar to Cidades@ portal).195196```197# Panorama of São Paulo198ibge_cidades(tipo="panorama", municipio="3550308")199200# Population history201ibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")202203# List available research204ibge_cidades(tipo="pesquisas")205```206207**Available indicators:** populacao, area, densidade, pib_per_capita, idh, escolarizacao, mortalidade, salario_medio, receitas, despesas208209### ibge_paises210211Query international country data.212213```214# List all countries215ibge_paises(tipo="listar")216217# Brazil details218ibge_paises(tipo="detalhes", pais="BR")219220# Search countries221ibge_paises(tipo="buscar", busca="Argentina")222223# Countries in Americas224ibge_paises(tipo="listar", regiao="americas")225```226227**Regions:** americas, europa, africa, asia, oceania228229### ibge_sidra230231Query SIDRA tables (IBGE's Automatic Recovery System).232233```234# Brazil population in 2023235ibge_sidra(tabela="6579", periodos="2023")236237# Population by state238ibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")239240# Census 2022 for São Paulo municipality241ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")242```243244**Common tables:**245| Code | Description |246|-----:|:------------|247| 6579 | Population estimates (annual) |248| 9514 | Census 2022 population |249| 4714 | Unemployment rate (PNAD) |250| 6706 | GDP at current prices |251252**Territorial levels:**253| Code | Level |254|-----:|:------|255| 1 | Brazil |256| 2 | Region (North, Northeast, etc.) |257| 3 | State (UF) |258| 6 | Municipality |259| 7 | Metropolitan Region |260| 106 | Health Region |261| 127 | Legal Amazon |262| 128 | Semi-arid |263264### ibge_censo265266Query Census data (1970-2022).267268```269# Population Census 2022270ibge_censo(ano="2022", tema="populacao")271272# Historical population series273ibge_censo(ano="todos", tema="populacao")274275# Literacy by state in 2010276ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")277```278279**Available themes:** populacao, alfabetizacao, domicilios, idade_sexo, religiao, cor_raca, rendimento, migracao, educacao, trabalho280281### ibge_indicadores282283Query economic and social indicators.284285```286# GDP287ibge_indicadores(indicador="pib")288289# IPCA last 12 months290ibge_indicadores(indicador="ipca", periodos="last 12")291292# Unemployment by state293ibge_indicadores(indicador="desemprego", nivel_territorial="3")294295# List all indicators296ibge_indicadores(indicador="listar")297```298299**Available indicators:**300| Category | Indicators |301|:---------|:-----------|302| Economic | pib, pib_variacao, pib_per_capita, industria, comercio, servicos |303| Prices | ipca, ipca_acumulado, inpc |304| Labor | desemprego, ocupacao, rendimento, informalidade |305| Population | populacao, densidade |306| Agriculture | agricultura, pecuaria |307308### ibge_nomes309310Query name frequency and rankings.311312```313# Frequency of "Maria"314ibge_nomes(tipo="frequencia", nomes="Maria")315316# Compare names317ibge_nomes(tipo="frequencia", nomes="João,José,Pedro")318319# Ranking of names in 2000s320ibge_nomes(tipo="ranking", decada=2000)321322# Female names ranking323ibge_nomes(tipo="ranking", sexo="F")324```325326### ibge_malhas327328Get geographic meshes (maps).329330```331# Brazil with states332ibge_malhas(localidade="BR", resolucao="2")333334# São Paulo with municipalities335ibge_malhas(localidade="SP", resolucao="5")336337# Specific municipality338ibge_malhas(localidade="3550308")339340# SVG format341ibge_malhas(localidade="BR", formato="svg")342```343344**Resolution levels:**345| Value | Internal Divisions |346|:-----:|:-------------------|347| 0 | No divisions (outline only) |348| 2 | States |349| 5 | Municipalities |350351### bcb352353Query Central Bank of Brazil data.354355```356# SELIC last 12 months357bcb(indicador="selic", ultimos=12)358359# IPCA for 2023360bcb(indicador="ipca", dataInicio="01/01/2023", dataFim="31/12/2023")361362# Dollar exchange rate last 30 days363bcb(indicador="dolar_venda", ultimos=30)364```365366**Available indicators:** selic, cdi, tr, ipca, ipca_acum, igpm, inpc, dolar_compra, dolar_venda, euro, desemprego367368### datasaude369370Query health indicators via IBGE/DataSUS.371372```373# Infant mortality in Brazil374datasaude(indicador="mortalidade_infantil")375376# Life expectancy by state377datasaude(indicador="esperanca_vida", nivel_territorial="3")378379# List indicators380datasaude(indicador="listar")381```382383**Available indicators:** mortalidade_infantil, esperanca_vida, nascidos_vivos, obitos, fecundidade, saneamento_agua, saneamento_esgoto, plano_saude384385## APIs Used386387### IBGE APIs388389- **Localities**: `servicodados.ibge.gov.br/api/v1/localidades`390- **Names**: `servicodados.ibge.gov.br/api/v2/censos/nomes`391- **Aggregates/SIDRA**: `servicodados.ibge.gov.br/api/v3/agregados`392- **SIDRA API**: `apisidra.ibge.gov.br/values`393- **Meshes**: `servicodados.ibge.gov.br/api/v3/malhas`394- **News**: `servicodados.ibge.gov.br/api/v3/noticias`395- **Population**: `servicodados.ibge.gov.br/api/v1/projecoes/populacao`396- **CNAE**: `servicodados.ibge.gov.br/api/v2/cnae`397- **Calendar**: `servicodados.ibge.gov.br/api/v3/calendario`398- **Countries**: `servicodados.ibge.gov.br/api/v1/paises`399- **Research**: `servicodados.ibge.gov.br/api/v1/pesquisas`400401### External APIs402403- **Central Bank (BCB)**: `api.bcb.gov.br/dados/serie/bcdata.sgs` - Interest rates, exchange rates, inflation404405## Development406407```bash408# Build409npm run build410411# Watch mode412npm run watch413414# Run tests415npm test416417# Run tests in watch mode418npm run test:watch419420# Lint421npm run lint422423# Format424npm run format425426# Test with MCP inspector427npm run inspector428```429430## Project Structure431432```433ibge-br-mcp/434├── src/435│ ├── index.ts # Main MCP server436│ ├── types.ts # TypeScript types437│ ├── config.ts # Configuration and constants438│ ├── cache.ts # Request caching system439│ ├── retry.ts # Retry with exponential backoff440│ ├── errors.ts # Standardized error handling441│ ├── validation.ts # Input validation helpers442│ ├── metrics.ts # Metrics and logging443│ ├── utils/444│ │ └── formatters.ts # Formatting utilities445│ └── tools/446│ ├── index.ts # Tool exports447│ ├── estados.ts # ibge_estados448│ ├── municipios.ts # ibge_municipios449│ ├── localidade.ts # ibge_localidade450│ ├── geocodigo.ts # ibge_geocodigo451│ ├── censo.ts # ibge_censo452│ ├── populacao.ts # ibge_populacao453│ ├── sidra.ts # ibge_sidra454│ ├── sidra-tabelas.ts # ibge_sidra_tabelas455│ ├── sidra-metadados.ts# ibge_sidra_metadados456│ ├── indicadores.ts # ibge_indicadores457│ ├── cnae.ts # ibge_cnae458│ ├── calendario.ts # ibge_calendario459│ ├── comparar.ts # ibge_comparar460│ ├── malhas.ts # ibge_malhas461│ ├── malhas-tema.ts # ibge_malhas_tema462│ ├── vizinhos.ts # ibge_vizinhos463│ ├── bcb.ts # bcb464│ ├── datasaude.ts # datasaude465│ ├── pesquisas.ts # ibge_pesquisas466│ ├── nomes.ts # ibge_nomes467│ ├── noticias.ts # ibge_noticias468│ ├── paises.ts # ibge_paises469│ └── cidades.ts # ibge_cidades470├── tests/ # Test files471├── dist/ # Compiled files472├── package.json473├── tsconfig.json474├── vitest.config.ts475└── README.md476```477478## Testing479480The project includes a comprehensive test suite with 227 tests covering:481482- Validation functions483- Retry mechanism484- Formatting utilities485- Error handling486- Cache operations487- Integration tests with mocks488489```bash490npm test491```492493## Quality Assurance494495This project maintains high code quality standards:496497- **227 automated tests** covering validation, caching, retry logic, formatting, and integrations498- **97%+ test coverage** on core modules (cache, validation, errors, types)499- **ESLint** for code linting with zero warnings500- **Prettier** for consistent code formatting501- **TypeScript strict mode** for type safety502- **Automated CI/CD** via GitHub Actions503504Run tests locally:505```bash506# Run all tests507npm test508509# Run tests with coverage510npm run test:coverage511512# Run linter513npm run lint514```515516## License517518MIT519520## Author521522Sidney Bissoli523524## References525526- [IBGE - Data Service](https://servicodados.ibge.gov.br/api/docs/)527- [SIDRA - IBGE Automatic Recovery System](https://sidra.ibge.gov.br/)528- [Model Context Protocol](https://modelcontextprotocol.io/)529- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)530
Full transparency — inspect the skill content before installing.