# IBGE Localidades MCP

> IBGE Localidades — Cidades do Brasil gives your AI agent direct access to Brazil’s official geographic database. It provides a complete map of all 5,570 municipalities across the 27 states, including the full administrative hierarchy and metropolitan areas, with zero authentication required.

## Overview
- **Category:** data-management
- **Price:** Free
- **Tags:** municipalities, geospatial-data, administrative-hierarchy, brazil-geography, location-services

## Description

Need location data for Brazil? This MCP connects your agent directly to the authoritative IBGE source—the same data government agencies, fintechs, and logistics firms rely on. Forget guessing city codes or struggling with incomplete regional maps. You can ask about any specific municipality using its 7-digit code, pull lists of all cities within a state (by UF abbreviation), or get a breakdown of the five major macro-regions. It even handles metropolitan areas like São Paulo and Rio de Janeiro by listing their constituent parts.

This is vital for anyone building agents that need to understand Brazilian geography accurately. If your workflow depends on correct administrative data, connecting through Vinkius and using this MCP means you're working with the definitive source. You just ask your agent about a state or region, and it gives you the full structure—from the macro-region all the way down to the specific city code.

## Tools

### list_estados
Provides a comprehensive list of all 27 states in Brazil and their official codes.

### get_municipios_por_uf
Lists all municipalities belonging to a Brazilian state, given the two-letter UF abbreviation.

### get_municipio
Retrieves full details for a specific city using its 7-digit IBGE code.

### list_regioes
Returns the five major administrative macro-regions used across Brazil.

### list_regioes_metropolitanas
Lists all designated metropolitan areas within a given state.

## Prompt Examples

**Prompt:** 
```
List all municipalities in the state of São Paulo
```

**Response:** 
```
🇧🇷 **São Paulo — 645 Municipalities**

1. Adamantina (3500105)
2. Adolfo (3500204)
3. Aguaí (3500303)
...
645. Votorantim (3557006)

São Paulo is Brazil's largest state by municipality count, representing 11.6% of all Brazilian cities.
```

**Prompt:** 
```
What is the IBGE code for the city of Rio de Janeiro?
```

**Response:** 
```
📍 **Rio de Janeiro**

- IBGE Code: 3304557
- Microregion: Rio de Janeiro
- Mesoregion: Metropolitana do Rio de Janeiro
- State: RJ (33)
- Macro-region: Sudeste
```

**Prompt:** 
```
What are the metropolitan regions in the state of Minas Gerais?
```

**Response:** 
```
🏙️ **Minas Gerais — Metropolitan Regions**

1. RM de Belo Horizonte (34 municipalities, pop ~5.8M)
2. RM do Vale do Aço (28 municipalities)
3. Colar Metropolitano (16 municipalities)

The Belo Horizonte metro area is Brazil's third largest, after São Paulo and Rio de Janeiro.
```

## Capabilities

### Get detailed municipal data
You can retrieve the full administrative profile for any single city using its official 7-digit IBGE code.

### List all cities in a state
The MCP lists every municipality within a specific Brazilian state, requiring only the two-letter UF abbreviation (like SP or RJ).

### Identify all states
You get a complete list of Brazil's 27 states and their corresponding codes.

### Map macro-regions
The agent can provide the names and structures of the five main Brazilian macro-regions (Norte, Nordeste, etc.).

### Detail metropolitan areas
It lists all recognized metropolitan regions for a state, helping you distinguish between general and major urban centers.

## Use Cases

### Validating a complex shipping address
A logistics agent needs to verify if an incoming shipment address is valid. It first uses list_estados to confirm the state code, then gets_municipio using the 7-digit IBGE code to ensure the city and municipality structure is absolutely correct before generating a manifest.

### Segmenting market research by zone
A researcher wants to analyze consumer behavior across major economic zones. They call list_regioes, identify the target macro-region (e.g., Sudeste), and then use get_municipios_por_uf on states within that region.

### Building a comprehensive CRM lookup tool
A developer builds an address validator. The agent first calls list_estados to populate the main dropdown, and if the user selects 'São Paulo', it then uses get_municipios_por_uf to fill the secondary list accurately.

### Mapping all major urban centers
A city planner needs a full list of all metropolitan areas in Minas Gerais. They run list_regioes_metropolitanas, which immediately gives them the official designations and boundaries to work with.

## Benefits

- Stop dealing with vague location data. By using get_municipio, you guarantee your agent has the precise administrative profile for any city via its IBGE code.
- Need to scope a market? Use list_regioes to quickly understand which of Brazil's five macro-regions are relevant to your current project.
- Don't waste time checking state boundaries manually. With list_estados, you get all 27 UFs and their codes in one go for quick validation checks.
- Distinguish between a general city and a major urban cluster. Running list_regioes_metropolitanas identifies the official metro areas within any given state.
- The process of finding all cities in a large state is simple. Just call get_municipios_por_uf with the two-letter UF code, and you're done.

## How It Works

The bottom line is you get structured, official Brazilian geographic intelligence directly into your workflow without needing to manage any keys or endpoints.

1. Subscribe to this MCP. It's free and instant.
2. Your agent connects to the service using your Vinkius account credentials; no API keys are needed because IBGE data is open government source material.
3. You instruct your agent on the required location parameters (e.g., 'Find all municipalities in Minas Gerais') and it executes the necessary calls to structure the data.

## Frequently Asked Questions

**How do I list all cities in Brazil using get_municipios_por_uf?**
You provide the two-letter UF code (like 'BA' for Bahia). The MCP returns a full list of every municipality within that state, making it easy to build out comprehensive regional data sets.

**What is the best way to get details on a single city? Should I use get_municipio?**
Yes, using get_municipio is the most precise method. You just need that specific 7-digit IBGE code for the city you're interested in.

**Does this MCP handle metropolitan areas? Which tool do I use?**
Yes, list_regioes_metropolitanas is designed for this. It specifically pulls together all the constituent municipalities that make up a major urban center like Belo Horizonte.

**I need to know all Brazilian states. Which tool do I call?**
You simply run list_estados. This gives you an immediate, complete roster of all 27 UFs and their necessary codes to start your data queries.

**How do I get the list of Brazil's five major macro-regions using `list_regioes`?**
It lists the 5 macro-regions: Norte, Nordeste, Centro-Oeste, Sudeste, and Sul. This provides a high-level view, grouping all smaller states into their correct geographic zone for broader analysis.

**What specific format does the code need to be when I call `get_municipio`?**
The IBGE code must be exactly 7 digits long. This unique identifier pinpoints the municipality down to its most granular administrative level, ensuring precise data retrieval.

**If I already know the state abbreviation (UF), can I list cities using `get_municipios_por_uf`?**
Yes, you only need the 2-letter UF abbreviation. The tool uses that code to pull every corresponding municipality within that entire Brazilian state.

**How do I check which metropolitan areas belong to a specific state using `list_regioes_metropolitanas`?**
You supply the 2-letter UF abbreviation, and it returns all associated metropolitan regions. This helps you map out complex urban clusters that span multiple cities within one major state.

**Do I need an API key?**
No! IBGE data is 100% open government data. This server works instantly with zero configuration — just subscribe and start querying Brazilian geography.