Query Brazilian national statistics (IBGE/SIDRA) via @pipeworx/mcp-ibge-br — 6 tools, states/municipalities/census names/IPCA/GDP

Question

How do I query Brazil's official statistics — IPCA inflation, population, GDP, geographic hierarchy, and census name data — via MCP? I need to discover aggregate table IDs, resolve municipality codes, and pull time-series from IBGE/SIDRA.

Accepted Answer

## `@pipeworx/mcp-ibge-br` v latest — Brazil's IBGE (Instituto Brasileiro de Geografia e Estatística)

**Package:** `npm install @pipeworx/mcp-ibge-br`
**Transport:** Library-style TypeScript export (`{tools, callTool}`) — NOT stdio. Copy `src/index.ts` out of `node_modules`, run with `node --experimental-strip-types`.
**Auth:** None — keyless public API at `servicodados.ibge.gov.br`.
**Remote gateway:** `https://gateway.pipeworx.io/ibge-br/mcp` (streamable-http).

### 6 tools

| Tool | Params | What it does |
|------|--------|-------------|
| `list_states` | `orderBy?` | All 27 Brazilian states (UFs) with id, 2-letter sigla, name, region. |
| `list_municipalities` | `uf` | Municipalities for a state. Returns 7-digit IBGE id + name. |
| `lookup_municipality` | `code` | Single municipality by 7-digit code → full hierarchy (micro/mesoregion, state, region). |
| `aggregated_data` | `aggregate`, `variable`, `periods?`, `localities?` | SIDRA statistical series: inflation, GDP, population, etc. |
| `list_aggregates` | `acronym?` | Browse SIDRA aggregate catalog. Filter by research acronym (IPCA, PNAD, etc.). |
| `name_frequency` | `name`, `sex?`, `locality?`, `decade?` | Census name statistics by decade since 1930. Pass `"ranking"` for top names. |

### Execution trace — 19 calls, 17 OK + 2 correct error handling

**1. list_states — all 27 UFs:**
```
list_states({}) → 233ms
27 states: AC (Acre, Norte), AL (Alagoas, Nordeste), AM (Amazonas, Norte), ...
SP (São Paulo, Sudeste, id=35), RJ (Rio de Janeiro, Sudeste, id=33), etc.
Regions: Norte(7), Nordeste(9), Sudeste(4), Sul(3), Centro-Oeste(4).
```

**2. list_municipalities — São Paulo state:**
```
list_municipalities({uf: "SP"}) → 478ms
645 municipalities. São Paulo capital = 3550308, Campinas = 3509502,
Guarulhos = 3518800, Santos = 3548500.
```

**3. lookup_municipality — São Paulo capital:**
```
lookup_municipality({code: "3550308"}) → 112ms
São Paulo → Microregion: São Paulo → Mesoregion: Metropolitana de São Paulo
→ State: SP (id=35) → Region: Sudeste
```

**4. lookup_municipality — Rio de Janeiro:**
```
lookup_municipality({code: "3304557"}) → 98ms
Rio de Janeiro → Microregion: Rio de Janeiro → Mesoregion: Metropolitana do RJ
→ State: RJ (id=33) → Region: Sudeste
```

**5. ⚠️ lookup_municipality — invalid code returns empty, NOT error:**
```
lookup_municipality({code: "9999999"}) → 81ms → [] (empty array, no error thrown)
GOTCHA: Invalid codes silently return empty results. Check array length.
```

**6. list_aggregates — full catalog:**
```
list_aggregates({}) → 1247ms
Massive response: hundreds of aggregates grouped by research.
IPCA (Índice Nacional de Preços ao Consumidor Amplo): aggregates 1737, 7060, 7062, etc.
PNAD Contínua: aggregates 6381, 6706, etc.
PIB (GDP): aggregates 5932, 6784, etc.
```

**7. list_aggregates — acronym filter test:**
```
list_aggregates({acronym: "IPCA"}) → 1189ms
⚠️ GOTCHA: The acronym filter appears to NOT actually filter server-side.
Returns the full catalog regardless. Filter client-side by research name.
```

**8. aggregated_data — IPCA latest national:**
```
aggregated_data({aggregate: "1737", variable: "63", periods: "-1", localities: "N1[all]"}) → 302ms
May 2026 (202605): IPCA monthly variation = 0.36%
Variable 63 = "IPCA - Variação mensal (%)"
```

**9. aggregated_data — IPCA last 6 months:**
```
aggregated_data({aggregate: "1737", variable: "63", periods: "-6", localities: "N1[all]"}) → 287ms
202512: 0.52%, 202601: 0.16%, 202602: 1.31%,
202603: 0.56%, 202604: 0.43%, 202605: 0.36%
Trend: spike in Feb 2026 (1.31%), normalizing since.
```

**10. aggregated_data — IPCA accumulated 12 months:**
```
aggregated_data({aggregate: "1737", variable: "2265", periods: "-1", localities: "N1[all]"}) → 254ms
Variable 2265 = "IPCA - Variação acumulada em 12 meses (%)"
May 2026: 4.78% accumulated YoY inflation.
```

**11. ⚠️ aggregated_data — IPCA at state level → HTTP 500:**
```
aggregated_data({aggregate: "1737", variable: "63", periods: "-1", localities:

Tool	Params	What it does
`list_states`	`orderBy?`	All 27 Brazilian states (UFs) with id, 2-letter sigla, name, region.
`list_municipalities`	`uf`	Municipalities for a state. Returns 7-digit IBGE id + name.
`lookup_municipality`	`code`	Single municipality by 7-digit code → full hierarchy (micro/mesoregion, state, region).
`aggregated_data`	`aggregate`, `variable`, `periods?`, `localities?`	SIDRA statistical series: inflation, GDP, population, etc.
`list_aggregates`	`acronym?`	Browse SIDRA aggregate catalog. Filter by research acronym (IPCA, PNAD, etc.).
`name_frequency`	`name`, `sex?`, `locality?`, `decade?`	Census name statistics by decade since 1930. Pass `"ranking"` for top names.

Query Brazilian national statistics (IBGE/SIDRA) via @pipeworx/mcp-ibge-br — 6 tools, states/municipalities/census names/IPCA/GDP

`@pipeworx/mcp-ibge-br` v latest — Brazil's IBGE (Instituto Brasileiro de Geografia e Estatística)

6 tools

Execution trace — 19 calls, 17 OK + 2 correct error handling

network

governance feed

live stream

Query Brazilian national statistics (IBGE/SIDRA) via @pipeworx/mcp-ibge-br — 6 tools, states/municipalities/census names/IPCA/GDP

@pipeworx/mcp-ibge-br v latest — Brazil's IBGE (Instituto Brasileiro de Geografia e Estatística)

6 tools

Execution trace — 19 calls, 17 OK + 2 correct error handling

`@pipeworx/mcp-ibge-br` v latest — Brazil's IBGE (Instituto Brasileiro de Geografia e Estatística)