IBGE Brasil MCP

Returns the full document for an id obtained from search, as { id, title, text, url, metadata }: text is the readable content (Markdown) and url the canonical public page to cite.

Companion of search in the OpenAI Deep Research contract, over the IBGE (Brazilian official statistics: SIDRA tables, municipalities, known indicators) catalog. Only ids returned by search are valid; an unknown id returns an error. The ibge_* tools (ibge_sidra, ibge_cidades, ibge_indicadores, ibge_comparar…) remain the tools for data queries.

Behavior: read-only and idempotent — a live GET against the public source when the document needs it.

Queries IBGE release and collection calendar.

Features:

• List upcoming survey releases

• Filter by product (IPCA, PNAD, GDP, etc.)

• Filter by period

• Distinguish releases from field collections

Event types:

• Release: Publication of survey results

• Collection: Field research period

Examples:

• Upcoming releases: (no parameters)

• IPCA releases: produto="IPCA"

• 2024 calendar: de="01/01/2024", ate="31/12/2024"

• Field collections: tipo="coleta"

Use a different tool when:

• Already-published news and releases → ibge_noticias

Behavior: read-only and idempotent — a live GET against the public IBGE Calendário API. Returns a Markdown list.

Queries IBGE Demographic Census data (1970-2022).

Simplified tool to access census data without knowing SIDRA table codes.

Available years: 1970, 1980, 1991, 2000, 2010, 2022

Available themes:

• populacao: Resident population

• alfabetizacao: Literacy rate

• domicilios: Housing characteristics

• idade_sexo: Age pyramid

• religiao: Religion distribution

• cor_raca: Race/color

• rendimento: Monthly income

• educacao: Education level

• trabalho: Employment

Examples:

• Population 2022: ano="2022", tema="populacao"

• Historical series: ano="todos", tema="populacao"

• Literacy 2010 by state: ano="2010", tema="alfabetizacao", nivel_territorial="3"

• List tables: tema="listar"

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions over census data ("which municipality had the largest 2022 population?") use estatisticas=true — full distribution + top/bottom computed over ALL rows before truncation; agruparPor="" ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.

Use a different tool when:

• One municipality's current panel (estimate, HDI, GDP) → ibge_cidades

• Comparing/ranking localities → ibge_comparar

• An arbitrary SIDRA table → ibge_sidra

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.

Queries municipal indicators from IBGE (similar to Cidades@ portal).

Features:

• General overview of a municipality (population, HDI, GDP, etc.)

• Query specific indicators

• Historical indicator data over years

• List available surveys and indicators

Available indicators: populacao, area, densidade, pib_per_capita, idh, escolarizacao, mortalidade, salario_medio, receitas, despesas

Examples:

• São Paulo overview: tipo="panorama", municipio="3550308"

• Population history: tipo="historico", municipio="3550308", indicador="populacao"

• View surveys: tipo="pesquisas"

• Available indicators: tipo="indicador"

This tool is the panel for a SINGLE municipality (Cidades@). Use a different tool when:

• Census themes / historical series → ibge_censo

• Comparing multiple municipalities → ibge_comparar

• A macro indicator time series → ibge_indicadores

Behavior: read-only and idempotent — a live GET against the public IBGE APIs (Cidades@/agregados). Returns Markdown plus a typed structuredContent payload.

Queries CNAE (National Classification of Economic Activities) from IBGE.

CNAE is the official classification for economic activities in Brazil.

Hierarchical structure:

• Section (letter A-U): 21 main categories

• Division (2 digits): 87 divisions

• Group (3 digits): 285 groups

• Class (4-5 digits): 673 classes

• Subclass (7 digits): 1,332 subclasses

Features:

• Search by CNAE code

• Search by activity description

• List by hierarchical level

• Show complete hierarchy

Examples:

• Search software: busca="software"

• Specific code: codigo="6201-5/01"

• View section: codigo="J"

• List divisions: nivel="divisoes"

Behavior: read-only and idempotent — a live GET against the public IBGE CNAE API. Returns Markdown.

Compares data between localities (municipalities or states).

Available indicators:

• populacao: Current population estimate

• populacao_censo: Census 2022 population

• pib: GDP per capita

• area: Territorial area (km²)

• densidade: Population density (inhab/km²)

• alfabetizacao: Literacy rate

• domicilios: Number of households

Features:

• Compare up to 10 localities at once

• Calculate statistics (max, min, average, variation)

• Generate ranked output

• Accept municipality codes (7 digits) or state codes (2 digits)

Examples:

• Compare capitals: localidades="3550308,3304557,4106902", indicador="populacao"

• Compare states: localidades="35,33,41", indicador="pib"

• Area ranking: localidades="3550308,3304557", formato="ranking"

• List indicators: indicador="listar"

Use this tool ONLY to rank/compare 2–10 localities on one indicator. For a single locality, use ibge_cidades (municipal panel), ibge_censo, or ibge_sidra.

Behavior: read-only and idempotent — a live GET against the public IBGE APIs (SIDRA and Localidades). Returns Markdown plus a typed structuredContent payload.

Queries Brazil health indicators, served through IBGE's SIDRA (some originally produced by DataSUS, e.g. mortality and births).

Mortality and Birth:

• mortalidade_infantil: Infant mortality rate

• nascidos_vivos: Live births by location

• obitos: Deaths by residence

Demographic Indicators:

• esperanca_vida: Life expectancy at birth

• fecundidade: Fertility rate

Sanitation:

• saneamento_agua: Water supply

• saneamento_esgoto: Sewage system

Health Coverage:

• plano_saude: Health insurance coverage

• autoavaliacao_saude: Self-rated health status

Territorial levels: 1=Brazil, 2=Region, 3=State, 6=Municipality

Examples:

• Infant mortality: indicador="mortalidade_infantil"

• Life expectancy by state: indicador="esperanca_vida", nivel_territorial="3"

• Deaths in SP: indicador="obitos", nivel_territorial="3", localidade="35"

• List indicators: indicador="listar"

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest infant mortality?", "median life expectancy across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="" ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.

Use a different tool when:

• A single municipality's general panel (which also includes infant mortality) → ibge_cidades

• Population/demographic counts (not health-specific) → ibge_censo or ibge_sidra

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.

Lists all Brazilian states from IBGE.

Features:

• Lists all 27 states (26 states + Federal District)

• Filter by region (North, Northeast, Southeast, South, Central-West)

• Sort by ID, name, or abbreviation

Examples:

• List all states: (no parameters)

• Northeast states: regiao="NE"

• Sorted by abbreviation: ordenar="sigla"

Use a different tool when:

• Municipalities of a state → ibge_municipios

• Details/hierarchy of one locality by code → ibge_localidade

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown table.

Decodes IBGE codes or searches codes by locality name.

Features:

• Decode region, state, municipality, or district codes

• Search IBGE code by name

• Show complete geographic hierarchy

• Return related codes

Code structure:

• 1 digit: Region (1=North, 2=Northeast, 3=Southeast, 4=South, 5=Central-West)

• 2 digits: State (11-53)

• 7 digits: Municipality

• 9 digits: District

Examples:

• Decode municipality: codigo="3550308"

• Decode state: codigo="35"

• Search by name: nome="São Paulo"

• Municipality in state: nome="Campinas", uf="SP"

This tool decodes a code's structure and resolves name→code at any level. Use a different tool when:

• You only need to list/search municipalities → ibge_municipios

• You want the full detailed record of one locality → ibge_localidade

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns Markdown.

Queries IBGE economic and social indicators.

Available indicators:

Economic:

• pib: quarterly GDP at current prices, R$ million (Brazil only)

• pib_variacao: quarterly GDP volume change, % over the same quarter of the previous year (Brazil only)

• pib_per_capita: annual GDP per capita at current prices, R$ (Brazil only)

• industria: industrial production index, general industry (2022=100)

• comercio: retail sales volume index (2022=100)

• servicos: services volume index (2022=100, Brazil only)

Prices:

• ipca: IPCA monthly change, %

• ipca_acumulado: IPCA accumulated over 12 months, %

• inpc: INPC monthly change, %

Labor:

• desemprego: Unemployment rate

• ocupacao: Employed people (thousands)

• rendimento: average real income from all jobs, R$ — each period is a ROLLING quarter (e.g. "jun-jul-ago 2026"), Brazil only

• informalidade: Informality rate

Population:

• populacao: Population estimate

• densidade: Population density

Examples:

• GDP: indicador="pib"

• IPCA last 12 months: indicador="ipca", periodos="last 12"

• Unemployment by state: indicador="desemprego", nivel_territorial="3"

• List indicators: indicador="listar"

Each indicator returns ONE variable — the one its name says; for another one of the same table (e.g. the year-to-date change) use ibge_sidra with variaveis.

What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps no earlier version.

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest unemployment?", "median informality rate across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="" (e.g. "Unidade da Federação", "Trimestre") ranks groups by descending sum. In this mode campos/formato are ignored and registros comes empty.

Use a different tool when:

• Comparing/ranking localities → ibge_comparar

• Census themes → ibge_censo

• One municipality's panel → ibge_cidades

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.

Returns details of a specific locality by IBGE code.

Features:

• State information (2-digit code)

• Municipality information (7-digit code)

• District information (9-digit code)

• Complete hierarchy (region, mesoregion, microregion)

Examples:

• São Paulo state: codigo=35

• São Paulo city: codigo=3550308

• District: codigo=355030805

This tool returns the full record of ONE locality you already have the code for. Use a different tool when:

• You have a name and need the code → ibge_municipios (municipalities) or ibge_geocodigo (any level)

• You want to decompose/understand a code's structure → ibge_geocodigo

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown record.

Gets geographic meshes (maps) from IBGE in GeoJSON, TopoJSON, or SVG format.

Features:

• Meshes for Brazil, regions, states, municipalities

• Different resolution levels (internal divisions)

• Different quality levels

• Formats: GeoJSON (data), TopoJSON (compact), SVG (image)

Locality types:

• "BR" or "1" = Entire Brazil

• State abbreviation (e.g., "SP", "RJ")

• State code (e.g., "35" for SP)

• Municipality code (7 digits)

Resolution (internal divisions):

• 0 = Outline only

• 2 = States

• 5 = Municipalities

Examples:

• Brazil with states: localidade="BR", resolucao="2"

• São Paulo with municipalities: localidade="SP", resolucao="5"

• SVG format: localidade="BR", formato="svg"

Use a different tool when:

• Thematic meshes (biomes, Legal Amazon, semi-arid, metropolitan regions) → ibge_malhas_tema

Behavior: read-only and idempotent — a live GET against the public IBGE Malhas API. Returns the mesh in the requested format (GeoJSON, TopoJSON, or SVG).

Lists what a THEMATIC territorial recorte of Brazil contains: how many features, with which codes and names, and the URL to download its geometry.

Available recortes:

• biomas: the six continental biomes

• amazonia_legal: Legal Amazon boundary

• semiarido: semi-arid area

• costeiro: coastal municipalities

• fronteira: border-strip municipalities

• metropolitana: metropolitan regions

• ride: Integrated Development Regions

• listar: the catalogue itself, without querying the source

Filtering with codigo: only the recortes that have a per-feature code accept it — biomas (the biome code) and the two municipality ones, costeiro and fronteira (the 7-digit IBGE municipality code). Ask without codigo to see what exists; biome codes come from the source, not from a fixed table.

GEOMETRY IS NOT IN THE RESPONSE, on purpose: one biome polygon alone is over 9 MB. The response carries the attributes plus a canonical WFS URL that returns the recorte with geometry in GeoJSON.

Use a different tool when:

• Administrative meshes WITH geometry (country/region/state/municipality outlines) → ibge_malhas

Behavior: read-only and idempotent — a live GET against the public IBGE Geosserviços WFS (IBGE Geociências), which is a different service from the Malhas API and the only one that publishes these recortes. Returns Markdown plus a typed structuredContent payload.

Lists Brazilian municipalities from IBGE.

Features:

• List municipalities by state (using state abbreviation)

• List all municipalities in Brazil (5,570 municipalities)

• Search by municipality name

• Returns 7-digit IBGE code

Examples:

• São Paulo municipalities: uf="SP"

• Search by name: busca="Campinas"

• MG municipalities containing "Belo": uf="MG", busca="Belo"

Use a different tool when:

• Resolve/decode a code at any level (region, state, district), not just municipalities → ibge_geocodigo

• Full details/hierarchy of one locality by code → ibge_localidade

• Neighboring municipalities → ibge_vizinhos

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown table.

Queries name frequency and rankings in Brazil (IBGE).

Features:

1. Name frequency (tipo='frequencia'):

   • Birth frequency by decade

   • Multiple names separated by comma

   • Filter by sex and locality

2. Name ranking (tipo='ranking'):

   • Most popular names

   • Filter by decade, sex, and locality

Available decades: 1930-2010

Examples:

• Frequency of "Maria": tipo="frequencia", nomes="Maria"

• Compare names: tipo="frequencia", nomes="João,José,Pedro"

• 2000s ranking: tipo="ranking", decada=2000

• Female names: tipo="ranking", sexo="F"

Behavior: read-only and idempotent — a live GET against the public IBGE Nomes (Censo) API. Returns a Markdown table.

Searches and lists already-published IBGE news articles and press releases.

Use this to find recent IBGE publications or announcements about a survey or topic — when an indicator was released, or news mentioning a term like "censo". Results are sorted newest-first; with no parameters it returns the 10 most recent items.

Parameters:

• busca: free-text term to match (e.g. "PIB", "censo")

• tipo: "release" (official publication of survey results) or "noticia" (general news); omit for both

• de / ate: date range, format DD/MM/AAAA (e.g. de="01/01/2024", ate="31/12/2024")

• destaque: true to return only featured items

• quantidade: how many to return (default 10, max 100); pagina: page number to page through more

Each item returns: title, type (release/news), publication date, editoria (section), related products/surveys, a featured flag, a plain-text summary, and a link to the full article. The header reports the total count and current page.

Examples:

• Latest 10 news: (no parameters)

• Search census: busca="censo"

• 2024 news: de="01/01/2024", ate="31/12/2024"

• Releases only: tipo="release"

Use a different tool when:

• Scheduled/upcoming release dates (not yet published) → ibge_calendario

Behavior: read-only and idempotent — a live GET against the public IBGE Notícias API. Returns a Markdown list.

Queries international country data via IBGE.

Features:

• List all countries (following UN M49 methodology)

• Country details (area, languages, currency, location) with the latest published value of country indicators — by default population, GDP, GDP per capita, HDI and life expectancy

• Pick other indicators with indicadores="<ids or aliases separated by |>"

• Indicator catalog as published by IBGE (34 indicators: economy, population, health, environment, networks), with unit and scale

• Search countries by name

• Filter by region/continent

Each indicator value is the most recent one the source publishes for that country, with its year or period (some are 3- or 5-year ranges like "2021-2023"), as text (it can be "<2.5"), plus unit and scale (multiplicador) — null when the source has none.

Available regions: americas, europa, africa, asia, oceania

Country codes: Use ISO-ALPHA-2 (e.g., BR, US, AR, PT, JP)

Examples:

• List all: tipo="listar"

• Brazil details: tipo="detalhes", pais="BR"

• Chosen indicators: tipo="detalhes", pais="AR", indicadores="idh|77852"

• Search: tipo="buscar", busca="Argentina"

• Americas countries: tipo="listar", regiao="americas"

• Indicator catalog: tipo="indicadores"

Behavior: read-only and idempotent — a live GET against the public IBGE Países API. Returns Markdown.

Lists available IBGE surveys and their tables.

Features:

• List all IBGE surveys (Census, PNAD, GDP, etc.)

• Search by name or code

• Show details and tables of a specific survey

• Categorize surveys by theme

Main surveys:

• Census: Demographic, Agricultural, MUNIC

• PNAD Contínua: Employment, income, education

• National Accounts: GDP, investments

• Economic Surveys: Industry, Commerce, Services

• Price Indices: IPCA, INPC

Examples:

• List all: (no parameters)

• Search population: busca="população"

• PNAD details: detalhes="pnad"

This lists surveys, not data. To find table codes use ibge_sidra_tabelas; to query data use ibge_sidra (or a wrapper: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades).

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA/Pesquisas API. Returns a Markdown list.

Queries SIDRA tables (IBGE's Automatic Recovery System).

SIDRA contains data from IBGE surveys like Census, PNAD, GDP, etc.

Common tables:

• 6579: Population estimates (annual)

• 9514: Census 2022 population

• 200: Census population (1970-2010)

• 4714: Population, territorial area and density (Census 2022)

• 4099: Unemployment rate (PNAD Contínua, quarterly)

• 5436: Average real income (PNAD Contínua, quarterly)

• 1846: Quarterly GDP at current prices (Brazil)

• 5938: Municipal GDP at current prices (annual, down to municipality)

• 6784: Annual GDP and GDP per capita (Brazil)

Territorial levels:

• 1: Brazil

• 2: Region (North, Northeast, etc.)

• 3: State (UF)

• 6: Municipality

• 7: Metropolitan Region

Examples:

• Brazil population 2023: tabela="6579", periodos="2023"

• Population by state: tabela="6579", nivel_territorial="3"

• Census 2022 by municipality: tabela="9514", nivel_territorial="6", localidades="3550308"

What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps no earlier version.

Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which municipality has the largest population?", "median GDP by state") use estatisticas=true — it computes min/max/mean/median/std-dev/labeled percentiles over ALL data rows BEFORE pagination and returns top/bottom rankings (default 10, cap 100 via topN), so one call answers what would otherwise require paging thousands of records. With agruparPor="" (e.g. "Unidade da Federação", "Ano") it ranks groups by descending sum, each with its own mini-distribution. Queries mixing several variables auto-group by "Variável" (units differ). SIDRA absence markers ("-", "..", "...", "X") are excluded from n. In this mode pagina/campos/formato are ignored and registros comes empty. Very large queries are refused by the source (since 2026-09-16 SIDRA tables are read through the Aggregates API, whose ceiling is lower than SIDRA's old 100,000-value cap: all municipalities × 12 yearly periods fails, × 8 works) — narrow periodos (e.g. "last 4") or raise nivel_territorial.

ibge_sidra is the low-level engine. Prefer a friendlier wrapper when it fits:

• Census themes (1970–2022) → ibge_censo

• Economic/social time series → ibge_indicadores

• Rank/compare 2–10 localities → ibge_comparar

• One municipality's panel → ibge_cidades Use ibge_sidra_tabelas and ibge_sidra_metadados to find a table code and its structure before querying.

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.

Returns metadata for a specific SIDRA table.

Features:

• General info (name, survey, subject, periodicity)

• Available territorial levels

• Variable list with units

• Classifications and categories

• Available periods

Use this tool to understand table structure BEFORE querying data with ibge_sidra.

Examples:

• Population table metadata: tabela="6579"

• Census 2022 metadata: tabela="9514"

• PNAD unemployment: tabela="4714"

Use this after finding a table code (ibge_sidra_tabelas) and before querying with ibge_sidra.

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown.

Lists and searches available SIDRA tables.

Features:

• List all SIDRA tables (aggregates)

• Search by table name: every word must match (AND), accents and case ignored, and everyday Portuguese is resolved to the IBGE's own wording (renda→rendimento, desemprego→desocupação, cidade→município, gênero→sexo); when that happens the response says so in notas_vocabulario

• Filter by survey (Census, PNAD, GDP, etc.)

• Shows code and name of each table

SIDRA contains data from various surveys:

• Demographic Census

• PNAD Contínua (employment, income)

• National Accounts (GDP)

• Industrial Survey

• Agricultural Survey

Examples:

• List tables: (no parameters)

• Search population tables: busca="população"

• Census tables: pesquisa="censo"

This is step 1 of the SIDRA workflow: find a table code → ibge_sidra_metadados (structure) → ibge_sidra (query). For common data, a wrapper is usually easier: ibge_censo, ibge_indicadores, ibge_comparar, ibge_cidades.

Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns a Markdown table.

Finds nearby/neighboring municipalities.

Features:

• Search by IBGE code (7 digits) or municipality name

• Returns municipalities in the same mesoregion (proximity approximation)

• Optionally includes population data

Note: Uses mesoregion as geographic proximity proxy. For exact spatial neighborhood, mesh processing would be required.

Examples:

• By code: municipio="3550308"

• By name: municipio="Campinas", uf="SP"

• With population: municipio="3550308", incluir_dados=true

Note: proximity is approximated by shared mesoregion (not exact spatial adjacency). For listing/searching municipalities, use ibge_municipios.

Behavior: read-only and idempotent — a live GET against the public IBGE Localidades API. Returns a Markdown list.

Searches the IBGE (Brazilian official statistics: SIDRA tables, municipalities, known indicators) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).

This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools search and fetch. Pass one of the returned ids to fetch to read the document. For direct questions and for data (values, series, rankings) prefer the ibge_* tools (ibge_sidra, ibge_cidades, ibge_indicadores, ibge_comparar…), which return the actual data with provenance — this is a catalog index, not a data query.

Query: natural language or keywords, Portuguese or English; accents and case are ignored.

Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.