# SIDRA Dados Censitários MCP MCP

> IBGE Censo & SIDRA — Dados Censitários gives you instant access to Brazil's official statistical records. Pull national and regional data covering GDP, demographics, labor force stats, inflation (IPCA), and agriculture production—all from one API. This is the foundational layer for any deep dive into Brazilian economic or population trends.

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

## Description

Need solid macro data? This MCP connects your agent directly to SIDRA, which manages Brazil's core statistics since 1940. You don't have to jump through multiple government websites just to get a reliable figure. Your AI client pulls everything—from national GDP figures down to municipal employment rates; from monthly IPCA indices to specific crop yields. It’s the backbone for anyone working with Brazilian economic intelligence.

Whether you're tracking how inflation impacts regional purchasing power or need demographic breakdowns by age and race, this MCP handles it. You can filter data by geography (state, region) and define exact time periods using your agent. If you use Vinkius to connect your preferred AI client, you get access to this massive catalog of tools alongside everything else. It's pure statistical power, structured for modern development.

## Tools

### list_agregados
Provides an index of all available SIDRA aggregate tables, grouped by the survey or topic they cover.

### get_agregado_data
Retrieves specific statistical figures from an aggregate table using defined variables, time periods, and geographic levels.

### get_agregado_metadados
Pulls the schema and field descriptions for a given SIDRA dataset so you know exactly what data points are available.

### get_agregado_periodos
Checks which specific time ranges (e.g., 2018 to 2023) are valid for a chosen statistical aggregate.

## Prompt Examples

**Prompt:** 
```
What is the latest IPCA inflation rate in Brazil?
```

**Response:** 
```
📊 **Brazil — IPCA (Consumer Price Index)**

Latest month: +0.43%
12-month accumulated: 4.62%
Top contributors: Food (+0.18%), Transportation (+0.12%)
Target range: 3.0% ± 1.5pp

Inflation remains within the Central Bank's target range.
```

**Prompt:** 
```
What is the GDP of the state of São Paulo?
```

**Response:** 
```
💰 **São Paulo — GDP**

GDP: R$ 2.7 trillion (2022)
Share of national GDP: 30.5%
Per capita GDP: R$ 58,200

São Paulo alone has a GDP larger than most Latin American countries — equivalent to Argentina's entire economy.
```

**Prompt:** 
```
What is the population of Brazil by macro-region?
```

**Response:** 
```
👥 **Brazil — Population by Macro-Region**

- Sudeste: 89.6M (41.8%)
- Nordeste: 57.7M (26.9%)
- Sul: 30.4M (14.2%)
- Norte: 19.2M (9.0%)
- Centro-Oeste: 17.4M (8.1%)

**Total: 214.3 million** (2022 Census)
```

## Capabilities

### Calculate regional economic indicators
Pull historical and current data points like GDP or per capita income for specific states or municipalities.

### Trace demographic shifts over time
Access census results, allowing you to track population changes based on age, sex, or educational levels across different years.

### Determine inflation rates and contributors
Get the monthly IPCA index and see exactly which goods—like food or transport—are driving price increases.

### List available datasets and schemas
Find out what data is even available by listing all the core SIDRA aggregate tables grouped by survey type.

## Use Cases

### Comparing inflation across regions
A user needs to know if IPCA rates in Rio de Janeiro are stable compared to São Paulo. They use `list_agregados` to find the correct index, then run `get_agregado_data` specifying 'Rio de Janeiro' and 'São Paulo' while filtering for the last 12 months of data.

### Building a demographic report
A researcher needs to track population growth segmented by age group and race. They use `get_agregado_metadados` first, confirming the available census variables, before pulling the full dataset with `get_agregado_data`.

### Auditing a market report
An analyst needs to verify if a competitor's claim about agricultural output is accurate. They use `list_agregados` to find the crop production table, check available years with `get_agregado_periodos`, and finally pull the data using `get_agregado_data`.

### Analyzing labor market shifts
A consulting firm needs to model job changes. They use the MCP to retrieve PNAD labor force survey data by sector, enabling them to map recent employment trends across various Brazilian regions.

## Benefits

- You don't spend time on manual data cleaning or cross-referencing multiple IBGE sites. The structured access lets your agent pull clean, ready-to-use figures directly into your workflow.
- The `list_agregados` tool lets you quickly scope out the entire statistical universe—from labor statistics to agricultural yields—before writing a single query.
- You get precise control over variables and geography. Instead of general trends, you can pull data for 'São Paulo' specifically, or just the 'Nordeste' region using `get_agregado_data`.
- The system handles complexity: You don't need to know how SIDRA organizes its 10,000+ tables. Your agent manages that mapping automatically.
- You can check data validity upfront. Using `get_agregado_periodos` prevents your script from failing because you requested a date range the dataset never recorded.

## How It Works

The bottom line is, you move from identifying the dataset to retrieving the structured data payload in three defined steps.

1. First, use `list_agregados` to see a high-level list of all available statistical datasets and identify the one you need.
2. Next, call `get_agregado_metadados` to confirm the specific variables, fields, and data structure for that dataset. You're defining your parameters here.
3. Finally, use `get_agregado_data`, providing the required geography (state/municipality), time range, and variable codes to pull the actual figures.

## Frequently Asked Questions

**How do I find out what datasets are available using list_agregados?**
Use `list_agregados` first; it gives you an index of all SIDRA aggregate tables, grouping them by their survey topic. This is your starting point for knowing what data exists.

**What should I do if my chosen dataset has multiple years?**
You must run `get_agregado_periodos` to confirm the exact available date range for that specific aggregate. This prevents your agent from querying invalid time periods.

**Does get_agregado_data require me to know all the field codes?**
No, but it helps. You should first call `get_agregado_metadados` to review the schema and find the correct variable and level codes before running `get_agregado_data`.

**Is this data suitable for investment modeling?**
Yes. It provides granular economic indicators like GDP, employment (PNAD), and IPCA decomposition, which are standard inputs for advanced financial modeling.

**When I run `get_agregado_data`, what happens if my requested combination of variables or regions doesn't exist?**
The tool returns a structured JSON error message. It won't just fail; it will specify exactly which parameter is invalid, like an unavailable variable code or an uncombined region pairing.

**Do I need to run `list_agregados` first to know how to use the other tools?**
It's highly recommended. Using `list_agregados` gives your AI client a structured inventory of all available tables grouped by survey, helping you scope your query before hitting the data retrieval tools.

**If I need to analyze multiple different surveys, is there a way to use one tool for everything?**
No. Each aggregate dataset must be queried individually using its specific code. You'll need to run `get_agregado_metadados` for each survey you intend to combine.

**What is the best way to handle performance and avoid rate limits when retrieving large datasets with `get_agregado_data`?**
Querying data in logical chunks helps. Plan your requests by identifying key variables first, then use a sequence of focused calls rather than one massive request.

**How many aggregate tables are available?**
SIDRA contains **over 10,000 aggregate tables** spanning all IBGE surveys since the 1940s. Each table can be filtered by geographic level (Brazil, region, state, municipality), time period, and dozens of classification variables.