# IBGE SIDRA MCP

> IBGE Agregados (SIDRA) gives you direct access to Brazil's official statistical databases. Use this MCP to query demographic and economic data from IBGE SIDRA, allowing your agent to search for specific surveys, check metadata details, find available variables, or map geographic levels without navigating complex web portals.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** brazil, demographics, statistics, census, economic-indicators, data-query

## Description

Accessing Brazilian statistics used to mean days lost clicking through convoluted government websites. Now, you can speak in natural language and get exactly what you need from the official IBGE SIDRA database. This MCP lets your agent talk directly to the source of Brazil’s demographic and economic data.

Instead of manually figuring out which tables exist or what variables are available for a specific survey, you simply ask. The system handles the complexity of locating the right aggregate IDs and checking the required parameters—whether that's confirming the correct time period or identifying the necessary regional level. All this power is housed within Vinkius, making it easy to connect to your preferred AI client.

It’s about moving from manual data hunting to direct statistical query execution.

## Tools

### get_localidades
Retrieves all geographic levels (like state or city) available for a specified data aggregate.

### get_metadados
Fetches the complete documentation and context rules for any specific statistical table.

### get_periodos
Determines which time ranges or years of data are available for a given survey.

### get_variaveis
Lists every single measurable variable (the columns) that the chosen dataset contains.

### list_agregados
Allows you to search and list available statistical surveys or tables by topic.

## Prompt Examples

**Prompt:** 
```
List all IBGE aggregates related to 'PIB' (GDP).
```

**Response:** 
```
I've found several aggregates related to GDP. For example, Aggregate 5932 (PIB a preços correntes) and Aggregate 1612 (Contas Regionais). Which one would you like to explore?
```

**Prompt:** 
```
What variables are available for aggregate 1737?
```

**Response:** 
```
For aggregate 1737, the available variables include: 'Número de empresas e outras organizações' (ID: 628), 'Pessoal ocupado total' (ID: 629), and 'Salários e outras remunerações' (ID: 630).
```

**Prompt:** 
```
Show me the available geographic levels for aggregate 5932.
```

**Response:** 
```
Aggregate 5932 supports the following geographic levels: 'Brasil' (N1), 'Grande Região' (N2), 'Unidade da Federação' (N3), and 'Município' (N6).
```

## Capabilities

### Find available datasets
You can list and filter all IBGE aggregates (surveys/tables) by subject or classification.

### Check data context and rules
Retrieve detailed metadata for any specific aggregate to understand its methodology and scope.

### Identify required fields
List all variables available within a chosen aggregate, ensuring you select the right metrics before querying.

### Define time ranges
Determine which historical or future periods are available for any given survey.

### Filter by location
See every territorial level, from national to municipal, that a specific dataset supports.

## Use Cases

### Modeling regional economic shifts
A user needs to compare employment rates across five Brazilian states over the last decade. They first run `list_agregados` to find the correct labor survey ID, then call `get_variaveis` for 'employment' and `get_localidades` to confirm all five states are included before running the final query.

### Verifying research scope
A researcher needs to write a paper citing specific census data. They use `get_metadados` on an aggregate ID to ensure they understand the exact date, methodology, and limitations of the source material before including it in their bibliography.

### Building time-series dashboards
A developer needs to display a variable's trend over 20 years. They first check `get_periodos` for available dates, confirm the necessary variables via `get_variaveis`, and then build the visualization using the confirmed data range.

## Benefits

- Instead of guessing which ID to query, use `list_agregados` to filter and find the exact survey you need based on your topic or time frame.
- Avoid data errors by first running `get_metadados`. This tool gives you the necessary context and rules for the dataset, so you know if the data is suitable for modeling.
- You can build historical series easily. By checking available time periods with `get_periodos`, your agent confirms the full temporal scope before building a report.
- Precision matters in stats. Use `get_variaveis` to get a definitive list of all metrics, ensuring you only query for existing columns and avoiding data gaps.
- Never worry about geography again. `get_localidades` tells you immediately if the dataset covers municipal levels or just state-level summaries.

## How It Works

The bottom line is, it takes messy manual steps of cross-referencing web documentation and turns them into a simple, multi-step query sequence.

1. First, use the MCP to list available aggregates to find the ID of the survey you need.
2. Next, query the metadata and variable tools using that aggregate ID to confirm data context, time periods, and location levels.
3. Finally, your agent executes the complex statistical retrieval based on all confirmed parameters.

## Frequently Asked Questions

**How can I find specific surveys related to a topic like 'Employment'?**
Use the `list_agregados` tool and provide a keyword in the `assunto` parameter. The agent will return a list of all relevant aggregate tables and their IDs.

**Can I see which years or months are available for a specific table ID?**
Yes! By using the `get_periodos` tool with the specific Aggregate ID, you can retrieve all available time intervals for that dataset.

**How do I know if a table has data at the city level (municípios)?**
Run the `get_localidades` tool for the target Aggregate ID. It will list all supported geographic levels, such as 'Brasil', 'Unidade da Federação', or 'Município'.

**How do I check what data fields are available for a specific aggregate? Should I use get_variaveis?**
Yes, running get_variaveis pulls the complete list of variables for any given aggregate. This is key because it gives you the exact IDs and names needed to structure your precise queries before fetching the actual data.

**I need data that combines several different subjects (e.g., labor force and industry). How do I filter those results?**
Use list_agregados for advanced filtering. You can apply multidimensional criteria, narrowing down the search by subject, classification, or period to pinpoint specific tables across IBGE's vast dataset.

**I found a table ID but I don’t know what the data means; is there a way to understand its context?**
Calling get_metadados retrieves the full documentation for that aggregate. This step is crucial because it explains the methodology, definitions, and precise scope of the statistical data you're dealing with.

**Do I need to worry about complex API keys or authentication before starting queries?**
No, this MCP service functions as a public data resource. You don't need custom credentials; just connect your AI agent through the Vinkius marketplace to start querying immediately.

**If I run multiple checks—like checking get_localidades and get_variaveis—will there be rate limits?**
The system handles standard query volumes efficiently. If you plan on batch processing massive amounts of data, always check Vinkius's usage guidelines to ensure your workflow stays within optimal operational parameters.