# IBGE Pesquisas — Brasil Cidades MCP

> IBGE Pesquisas — Brasil Cidades allows you to query Brazil's official municipal data engine. Access indicators on health, education, economy, and sanitation for any Brazilian municipality. You can rank cities by specific metrics or compare data across multiple research surveys and time periods.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** municipal-indicators, social-research, quality-of-life, public-policy, data-query

## Description

You need deep demographic insight into Brazilian municipalities. This MCP connects directly to the core database that powers the official IBGE Brasil Cidades portal. It lets you pull complex, granular data sets—covering everything from literacy rates and sanitation access to GDP per capita—for thousands of cities. Instead of downloading massive, unwieldy CSVs and manually cross-referencing years or topics, your agent handles the heavy lifting. You specify the region, the metric, and the time frame; it returns structured results ready for analysis. With Vinkius in place, this MCP gives your AI client access to a national catalog of indicators, letting you build data-driven reports without ever leaving your chat window.

## Tools

### list_pesquisas
Lists every available IBGE research program and census report ID so you know what data is in the system.

### get_indicadores
Pulls specific quality-of-life metrics for a given Brazilian survey ID, allowing you to see health or education scores.

### get_resultados
Retrieves raw survey data for specific geographic locations, using a country code or state code as input.

### get_ranking_indicador
Calculates and lists the top municipalities based on any chosen economic or social indicator.

## Prompt Examples

**Prompt:** 
```
What are the education indicators for the city of Curitiba?
```

**Response:** 
```
📚 **Curitiba — Education Indicators**

- Literacy rate: 97.8%
- Average schooling: 10.9 years
- IDEB (primary): 6.8
- School enrollment (6-14): 98.2%
- Higher education rate: 32.1%

Curitiba ranks in the top 5% of Brazilian municipalities for education.
```

**Prompt:** 
```
Which Brazilian cities have the highest GDP per capita?
```

**Response:** 
```
🏆 **Top 5 — GDP Per Capita**

1. São Desidério (BA) — R$ 309K
2. Paulínia (SP) — R$ 258K
3. Louveira (SP) — R$ 241K
4. Triunfo (RS) — R$ 234K
5. São Francisco do Conde (BA) — R$ 221K

Small industrial and agribusiness cities dominate the top.
```

**Prompt:** 
```
Compare health indicators between São Paulo and Salvador
```

**Response:** 
```
🏥 **Health Comparison**

| Indicator | São Paulo | Salvador |
|-----------|-----------|----------|
| Life expect. | 77.3 yrs | 73.8 yrs |
| Infant mort. | 10.2‰ | 15.4‰ |
| Physicians | 4.2/1000 | 2.8/1000 |
| Hospital beds | 3.1/1000 | 2.4/1000 |
```

## Capabilities

### Retrieve location metrics
Get detailed indicator scores for any specific city or state based on the chosen survey.

### Compare across surveys
Query the same metric (like education level) using different research databases, such as Census data or Agricultural reports.

### Identify top regions
Automatically rank multiple Brazilian municipalities based on a single indicator, like highest GDP per capita.

### Discover available data sets
List every research program and survey type the IBGE has published for municipal use.

## Use Cases

### Comparing Health Outcomes
A public health researcher needs to compare life expectancy between São Paulo (SP) and Salvador (BA). They run the query using `get_indicadores` for both locations, pulling data from the same core survey ID. The agent outputs a clean table showing all comparable metrics at once.

### Finding Economic Hotspots
A journalist wants to prove which Brazilian state has the most rapid economic growth in its smaller towns. They use `get_ranking_indicador` targeting 'GDP per capita' across all available data, immediately identifying the top 5 municipalities.

### Building a Historical Report
An ESG analyst needs to track changes in sanitation access over time. They first run `list_pesquisas` to confirm historical surveys are available, then use `get_indicadores` multiple times for the same metric across different years.

### Targeted Municipal Research
A local government official only cares about one city. They input the specific IBGE code and run `get_resultados`, pulling all available data points immediately, without needing to browse a massive web portal.

## Benefits

- Stop manual data scraping. Instead of visiting multiple IBGE pages and downloading different files for each metric, your agent queries the central database directly using `get_indicadores`.
- Quickly identify regional leaders. Need to know which cities have the highest GDP per capita? Use `get_ranking_indicador`. It generates a ranked list instantly, saving hours of spreadsheet sorting.
- Compare disparate data sets easily. You can check health metrics from one survey and compare them against income stats from another, all in one workflow.
- Know your sources upfront. Before you start, run `list_pesquisas` to get the full catalog of available research programs, ensuring you don't miss crucial historical data.
- Analyze multiple locations at once. You can input a state code and pull comparative results for all major municipalities in that region.

## How It Works

The bottom line is: You point to the data set, and the system handles locating the specific city and metric within that massive repository.

1. First, let your agent run `list_pesquisas` to find the exact name or ID of the data set you need (e.g., 'Censo Demográfico').
2. Next, tell it the specific location (state code, municipality code) and what indicator you want to measure.
3. The MCP then runs the query, fetching the raw results or calculating a ranking based on your request.

## Frequently Asked Questions

**How do I find out what surveys are available using get_indicadores?**
You shouldn't start with `get_indicadores`. First, run `list_pesquisas` to get the full catalog of research programs. This confirms you have the correct survey ID needed for your analysis.

**What do I use if I only want results for a single specific city?**
Use `get_resultados`. You input the location code (either a state or municipality IBGE code), and it retrieves all available raw data points for that exact spot.

**Can I compare multiple indicators in one call using get_indicadores?**
Yes. `get_indicadores` is designed to handle multiple metrics at once, letting you pull health, education, and income data from the same survey ID without separate calls.

**If I want a list of top-performing cities, which tool should I use? Use get_ranking_indicador.**
You must use `get_ranking_indicador`. This tool is specifically built to calculate and present a clear, ordered ranking based on your chosen metric.

**When I use get_resultados, what are the accepted formats for specifying a municipality or state?**
The tool accepts three primary identifiers: full country codes (BR), two-digit State Codes (UF like 33 for Rio de Janeiro), and specific IBGE municipal codes. You must provide one of these valid formats to successfully retrieve results.

**Can I use get_indicadores to compare indicator data from different years or time periods?**
Yes, the tool supports temporal queries by allowing you to specify a range of survey years. This lets you track changes in indicators over time, which is essential for longitudinal policy analysis.

**If I run get_indicadores and encounter missing data points, how do I troubleshoot them?**
Missing data usually means the indicator wasn't collected for that specific municipality or year. Double-check your survey ID using list_pesquisas to confirm if the indicator was part of the original research scope.

**When using get_ranking_indicador, how can I limit the rankings to a specific region or state (UF)?**
You must specify the geographical scope—the State Code (UF)—as an optional parameter when calling get_ranking_indicador. This ensures your ranking only includes data points from that selected region.

**Is this the same data as the Brasil Cidades portal?**
Yes! This server accesses the **exact same API** that powers the official [Brasil Cidades](https://cidades.ibge.gov.br) portal — the IBGE's premier municipal indicator platform.