Ibge Br MCP

1# ibge-br-mcp
2 
3[![npm version](https://img.shields.io/npm/v/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
4[![npm downloads](https://img.shields.io/npm/dm/ibge-br-mcp.svg)](https://www.npmjs.com/package/ibge-br-mcp)
5[![Tests](https://img.shields.io/badge/tests-227%20passed-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp)
6[![Coverage](https://img.shields.io/badge/coverage-core%2097%25-brightgreen.svg)](https://github.com/SidneyBissoli/ibge-br-mcp)
7[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8[![smithery badge](https://smithery.ai/badge/sidneybissoli/ibge-br-mcp)](https://smithery.ai/server/sidneybissoli/ibge-br-mcp)
9 
10MCP Server for IBGE (Brazilian Institute of Geography and Statistics) APIs.
11🇧🇷 [Leia em Português](README.pt-BR.md)
12 
13This 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.
14 
15## Features
16 
17- **23 specialized tools** covering all major IBGE data domains
18- **227 automated tests** with 97%+ core coverage
19- **Automatic caching** with configurable TTL for optimal performance
20- **Retry mechanism** with exponential backoff for network resilience
21- **Comprehensive validation** for all input parameters
22- **Standardized error handling** with helpful suggestions
23- **Full TypeScript support** with strict typing
24 
25## Available Tools
26 
27### Localities & Geography
28| 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 |
35 
36### 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 |
43 
44### Economic & Social Indicators
45| 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 |
50 
51### Municipal Data (Cidades@)
52| Tool | Description |
53|:-----|:------------|
54| `ibge_cidades` | Municipal indicators (population, HDI, GDP per capita, etc.) |
55 
56### International Data
57| Tool | Description |
58|:-----|:------------|
59| `ibge_paises` | Country data following UN M49 methodology |
60 
61### Demographics
62| Tool | Description |
63|:-----|:------------|
64| `ibge_populacao` | Real-time Brazilian population projection |
65| `ibge_nomes` | Name frequency and rankings in Brazil |
66 
67### Classifications
68| Tool | Description |
69|:-----|:------------|
70| `ibge_cnae` | CNAE (National Classification of Economic Activities) |
71 
72### Maps & Geographic Meshes
73| Tool | Description |
74|:-----|:------------|
75| `ibge_malhas` | Geographic meshes (GeoJSON, TopoJSON, SVG) |
76| `ibge_malhas_tema` | Thematic meshes (biomes, Legal Amazon, semi-arid) |
77 
78### External Data (BCB & Health)
79| Tool | Description |
80|:-----|:------------|
81| `bcb` | Central Bank data (SELIC, IPCA, exchange rates) |
82| `datasaude` | Health indicators via IBGE/DataSUS |
83 
84### News & Calendar
85| Tool | Description |
86|:-----|:------------|
87| `ibge_noticias` | IBGE news and press releases |
88| `ibge_calendario` | IBGE release and collection calendar |
89 
90## Installation
91 
92### Prerequisites
93 
94- Node.js 18.x or higher
95- npm or yarn
96 
97### From npm (recommended)
98 
99```bash
100npm install -g ibge-br-mcp
101```
102 
103### From source
104 
105```bash
106# Clone the repository
107git clone https://github.com/SidneyBissoli/ibge-br-mcp.git
108cd ibge-br-mcp
109 
110# Install dependencies
111npm install
112 
113# Build the project
114npm run build
115```
116 
117## Configuration
118 
119### Claude Desktop
120 
121Add to your Claude Desktop configuration file (`claude_desktop_config.json`):
122 
123```json
124{
125  "mcpServers": {
126    "ibge-br-mcp": {
127      "command": "npx",
128      "args": ["ibge-br-mcp"]
129    }
130  }
131}
132```
133 
134Or if installed from source:
135 
136```json
137{
138  "mcpServers": {
139    "ibge-br-mcp": {
140      "command": "node",
141      "args": ["/path/to/ibge-br-mcp/dist/index.js"]
142    }
143  }
144}
145```
146 
147### Claude Code
148 
149```json
150{
151  "mcpServers": {
152    "ibge-br-mcp": {
153      "command": "npx",
154      "args": ["ibge-br-mcp"]
155    }
156  }
157}
158```
159 
160## Tool Usage Examples
161 
162### ibge_estados
163 
164List all Brazilian states.
165 
166```
167# List all states
168ibge_estados
169 
170# States in Northeast region
171ibge_estados(regiao="NE")
172 
173# States sorted by abbreviation
174ibge_estados(ordenar="sigla")
175```
176 
177### ibge_municipios
178 
179List Brazilian municipalities.
180 
181```
182# Municipalities of São Paulo state
183ibge_municipios(uf="SP")
184 
185# Search municipalities by name
186ibge_municipios(busca="Campinas")
187 
188# Municipalities in MG containing "Belo"
189ibge_municipios(uf="MG", busca="Belo")
190```
191 
192### ibge_cidades
193 
194Query municipal indicators (similar to Cidades@ portal).
195 
196```
197# Panorama of São Paulo
198ibge_cidades(tipo="panorama", municipio="3550308")
199 
200# Population history
201ibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")
202 
203# List available research
204ibge_cidades(tipo="pesquisas")
205```
206 
207**Available indicators:** populacao, area, densidade, pib_per_capita, idh, escolarizacao, mortalidade, salario_medio, receitas, despesas
208 
209### ibge_paises
210 
211Query international country data.
212 
213```
214# List all countries
215ibge_paises(tipo="listar")
216 
217# Brazil details
218ibge_paises(tipo="detalhes", pais="BR")
219 
220# Search countries
221ibge_paises(tipo="buscar", busca="Argentina")
222 
223# Countries in Americas
224ibge_paises(tipo="listar", regiao="americas")
225```
226 
227**Regions:** americas, europa, africa, asia, oceania
228 
229### ibge_sidra
230 
231Query SIDRA tables (IBGE's Automatic Recovery System).
232 
233```
234# Brazil population in 2023
235ibge_sidra(tabela="6579", periodos="2023")
236 
237# Population by state
238ibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")
239 
240# Census 2022 for São Paulo municipality
241ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")
242```
243 
244**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 |
251 
252**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 |
263 
264### ibge_censo
265 
266Query Census data (1970-2022).
267 
268```
269# Population Census 2022
270ibge_censo(ano="2022", tema="populacao")
271 
272# Historical population series
273ibge_censo(ano="todos", tema="populacao")
274 
275# Literacy by state in 2010
276ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")
277```
278 
279**Available themes:** populacao, alfabetizacao, domicilios, idade_sexo, religiao, cor_raca, rendimento, migracao, educacao, trabalho
280 
281### ibge_indicadores
282 
283Query economic and social indicators.
284 
285```
286# GDP
287ibge_indicadores(indicador="pib")
288 
289# IPCA last 12 months
290ibge_indicadores(indicador="ipca", periodos="last 12")
291 
292# Unemployment by state
293ibge_indicadores(indicador="desemprego", nivel_territorial="3")
294 
295# List all indicators
296ibge_indicadores(indicador="listar")
297```
298 
299**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 |
307 
308### ibge_nomes
309 
310Query name frequency and rankings.
311 
312```
313# Frequency of "Maria"
314ibge_nomes(tipo="frequencia", nomes="Maria")
315 
316# Compare names
317ibge_nomes(tipo="frequencia", nomes="João,José,Pedro")
318 
319# Ranking of names in 2000s
320ibge_nomes(tipo="ranking", decada=2000)
321 
322# Female names ranking
323ibge_nomes(tipo="ranking", sexo="F")
324```
325 
326### ibge_malhas
327 
328Get geographic meshes (maps).
329 
330```
331# Brazil with states
332ibge_malhas(localidade="BR", resolucao="2")
333 
334# São Paulo with municipalities
335ibge_malhas(localidade="SP", resolucao="5")
336 
337# Specific municipality
338ibge_malhas(localidade="3550308")
339 
340# SVG format
341ibge_malhas(localidade="BR", formato="svg")
342```
343 
344**Resolution levels:**
345| Value | Internal Divisions |
346|:-----:|:-------------------|
347| 0 | No divisions (outline only) |
348| 2 | States |
349| 5 | Municipalities |
350 
351### bcb
352 
353Query Central Bank of Brazil data.
354 
355```
356# SELIC last 12 months
357bcb(indicador="selic", ultimos=12)
358 
359# IPCA for 2023
360bcb(indicador="ipca", dataInicio="01/01/2023", dataFim="31/12/2023")
361 
362# Dollar exchange rate last 30 days
363bcb(indicador="dolar_venda", ultimos=30)
364```
365 
366**Available indicators:** selic, cdi, tr, ipca, ipca_acum, igpm, inpc, dolar_compra, dolar_venda, euro, desemprego
367 
368### datasaude
369 
370Query health indicators via IBGE/DataSUS.
371 
372```
373# Infant mortality in Brazil
374datasaude(indicador="mortalidade_infantil")
375 
376# Life expectancy by state
377datasaude(indicador="esperanca_vida", nivel_territorial="3")
378 
379# List indicators
380datasaude(indicador="listar")
381```
382 
383**Available indicators:** mortalidade_infantil, esperanca_vida, nascidos_vivos, obitos, fecundidade, saneamento_agua, saneamento_esgoto, plano_saude
384 
385## APIs Used
386 
387### IBGE APIs
388 
389- **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`
400 
401### External APIs
402 
403- **Central Bank (BCB)**: `api.bcb.gov.br/dados/serie/bcdata.sgs` - Interest rates, exchange rates, inflation
404 
405## Development
406 
407```bash
408# Build
409npm run build
410 
411# Watch mode
412npm run watch
413 
414# Run tests
415npm test
416 
417# Run tests in watch mode
418npm run test:watch
419 
420# Lint
421npm run lint
422 
423# Format
424npm run format
425 
426# Test with MCP inspector
427npm run inspector
428```
429 
430## Project Structure
431 
432```
433ibge-br-mcp/
434├── src/
435│   ├── index.ts              # Main MCP server
436│   ├── types.ts              # TypeScript types
437│   ├── config.ts             # Configuration and constants
438│   ├── cache.ts              # Request caching system
439│   ├── retry.ts              # Retry with exponential backoff
440│   ├── errors.ts             # Standardized error handling
441│   ├── validation.ts         # Input validation helpers
442│   ├── metrics.ts            # Metrics and logging
443│   ├── utils/
444│   │   └── formatters.ts     # Formatting utilities
445│   └── tools/
446│       ├── index.ts          # Tool exports
447│       ├── estados.ts        # ibge_estados
448│       ├── municipios.ts     # ibge_municipios
449│       ├── localidade.ts     # ibge_localidade
450│       ├── geocodigo.ts      # ibge_geocodigo
451│       ├── censo.ts          # ibge_censo
452│       ├── populacao.ts      # ibge_populacao
453│       ├── sidra.ts          # ibge_sidra
454│       ├── sidra-tabelas.ts  # ibge_sidra_tabelas
455│       ├── sidra-metadados.ts# ibge_sidra_metadados
456│       ├── indicadores.ts    # ibge_indicadores
457│       ├── cnae.ts           # ibge_cnae
458│       ├── calendario.ts     # ibge_calendario
459│       ├── comparar.ts       # ibge_comparar
460│       ├── malhas.ts         # ibge_malhas
461│       ├── malhas-tema.ts    # ibge_malhas_tema
462│       ├── vizinhos.ts       # ibge_vizinhos
463│       ├── bcb.ts            # bcb
464│       ├── datasaude.ts      # datasaude
465│       ├── pesquisas.ts      # ibge_pesquisas
466│       ├── nomes.ts          # ibge_nomes
467│       ├── noticias.ts       # ibge_noticias
468│       ├── paises.ts         # ibge_paises
469│       └── cidades.ts        # ibge_cidades
470├── tests/                    # Test files
471├── dist/                     # Compiled files
472├── package.json
473├── tsconfig.json
474├── vitest.config.ts
475└── README.md
476```
477 
478## Testing
479 
480The project includes a comprehensive test suite with 227 tests covering:
481 
482- Validation functions
483- Retry mechanism
484- Formatting utilities
485- Error handling
486- Cache operations
487- Integration tests with mocks
488 
489```bash
490npm test
491```
492 
493## Quality Assurance
494 
495This project maintains high code quality standards:
496 
497- **227 automated tests** covering validation, caching, retry logic, formatting, and integrations
498- **97%+ test coverage** on core modules (cache, validation, errors, types)
499- **ESLint** for code linting with zero warnings
500- **Prettier** for consistent code formatting
501- **TypeScript strict mode** for type safety
502- **Automated CI/CD** via GitHub Actions
503 
504Run tests locally:
505```bash
506# Run all tests
507npm test
508 
509# Run tests with coverage
510npm run test:coverage
511 
512# Run linter
513npm run lint
514```
515 
516## License
517 
518MIT
519 
520## Author
521 
522Sidney Bissoli
523 
524## References
525 
526- [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