IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
A MCP server delivering live, sourced Brazilian public data from official IBGE APIs. It exposes a 22-toolset for model-context-protocol workflows, enabling access to frank public data streams and context models.
🛠️ Key Features
Tool count: 22 tools for accessing IBGE public data
Live data sourcing from IBGE APIs
Model Context Protocol (MCP) server integration
TypeScript implementation for strong typing
Topics include: brasil, censo, ibge, mcp, open-data, sidra
Readme excerpt indicates deployment and registry integration
🚀 Use Cases
Retrieve up-to-date Brazilian demographics and geography data
Integrate IBGE data into MCP-enabled workflows
Use SIDRA and open-data sources for model-context construction
Prototype MCP-backed data services for research dashboards
⚡ Developer Benefits
Clear MCP server structure with 22 tools
TypeScript-based, easy to extend
Grounded in official IBGE APIs for accuracy
Documentation-ready via readme excerpts and badges
⚠️ Limitations
Based on a readme excerpt; ensure full source access for complete tool details
Availability tied to IBGE API uptime and MCP ecosystem compatibility
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.
Parameters2
regiao
string
optional
Filtrar por região: N (Norte), NE (Nordeste), SE (Sudeste), S (Sul), CO (Centro-Oeste)
ordenar
string
optional
Campo para ordenação dos resultados
Raw schema
{
"type": "object",
"properties": {
"regiao": {
"description": "Filtrar por região: N (Norte), NE (Nordeste), SE (Sudeste), S (Sul), CO (Centro-Oeste)",
"type": "string",
"enum": [
"N",
"NE",
"SE",
"S",
"CO"
]
},
"ordenar": {
"default": "nome",
"description": "Campo para ordenação dos resultados",
"type": "string",
"enum": [
"id",
"nome",
"sigla"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_municipios
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.
Parameters3
uf
string
optional
Estado por sigla (SP), nome (São Paulo) ou código IBGE (35). Se não informado, retorna todos os municípios do Brasil.
busca
string
optional
Termo para buscar no nome do município
limite
number
optional
Número máximo de resultados (padrão: 100, máximo: 5570)
Raw schema
{
"type": "object",
"properties": {
"uf": {
"description": "Estado por sigla (SP), nome (São Paulo) ou código IBGE (35). Se não informado, retorna todos os municípios do Brasil.",
"type": "string"
},
"busca": {
"description": "Termo para buscar no nome do município",
"type": "string"
},
"limite": {
"default": 100,
"description": "Número máximo de resultados (padrão: 100, máximo: 5570)",
"type": "number",
"minimum": 1,
"maximum": 5570
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_localidade
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.
Tipo da localidade. Se não informado, será inferido pelo tamanho do código.
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "number",
"description": "Código IBGE da localidade (estado: 2 dígitos, município: 7 dígitos, distrito: 9 dígitos)"
},
"tipo": {
"description": "Tipo da localidade. Se não informado, será inferido pelo tamanho do código.",
"type": "string",
"enum": [
"estado",
"municipio",
"distrito"
]
}
},
"required": [
"codigo"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_sidra
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)
- 6706: GDP at current prices
- 5938: GDP per capita
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"
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="<column label>" (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. The query itself still respects SIDRA's official cap of 100,000 values.
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.
Parameters12
tabela
string
required
Código da tabela SIDRA (ex: 6579 para estimativas de população, 9514 para censo 2022)
variaveis
string
optional
IDs das variáveis separados por vírgula, ou 'allxp' para todas
Códigos das localidades separados por vírgula, ou 'all' para todas
periodos
string
optional
Períodos: 'last' para último, 'all' para todos, ou anos específicos (ex: 2020,2021,2022)
classificacoes
string
optional
Classificações no formato 'id[categorias]' (ex: '2[6794]' para sexo masculino)
formato
string
optional
Formato de saída: 'json' para dados brutos ou 'tabela' para formato legível
pagina
integer
optional
Página de resultados (100 registros por página)
campos
string
optional
Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta. Omitir traz todas.
estatisticas
boolean
optional
Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato
agruparPor
string
optional
Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)
Raw schema
{
"type": "object",
"properties": {
"tabela": {
"type": "string",
"description": "Código da tabela SIDRA (ex: 6579 para estimativas de população, 9514 para censo 2022)"
},
"variaveis": {
"default": "allxp",
"description": "IDs das variáveis separados por vírgula, ou 'allxp' para todas",
"type": "string"
},
"nivel_territorial": {
"default": "1",
"description": "Nível territorial (código N): 1=Brasil, 2=Região, 3=UF, 6=Município, 7=Região Metropolitana, 8=Mesorregião, 9=Microrregião, 10=Distrito, 11=Subdistrito, 13=RM/RIDE, 14=RIDE, 15=Aglomeração Urbana, 17=Região Geográfica Imediata, 18=Região Geográfica Intermediária, 105=Macrorregião de Saúde, 106=Região de Saúde, 114=Aglomerado Subnormal, 127=Amazônia Legal, 128=Semiárido",
"type": "string"
},
"localidades": {
"default": "all",
"description": "Códigos das localidades separados por vírgula, ou 'all' para todas",
"type": "string"
},
"periodos": {
"default": "last",
"description": "Períodos: 'last' para último, 'all' para todos, ou anos específicos (ex: 2020,2021,2022)",
"type": "string"
},
"classificacoes": {
"description": "Classificações no formato 'id[categorias]' (ex: '2[6794]' para sexo masculino)",
"type": "string"
},
"formato": {
"default": "tabela",
"description": "Formato de saída: 'json' para dados brutos ou 'tabela' para formato legível",
"type": "string",
"enum": [
"json",
"tabela"
]
},
"pagina": {
"default": 1,
"description": "Página de resultados (100 registros por página)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"campos": {
"description": "Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta. Omitir traz todas.",
"type": "string"
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato",
"type": "boolean"
},
"agruparPor": {
"description": "Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição",
"type": "string"
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"tabela"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_nomes
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.
Parameters6
tipo
string
required
Tipo de consulta: 'frequencia' para buscar nomes específicos ou 'ranking' para ver os mais populares
nomes
string
optional
Para tipo='frequencia': Nome ou nomes separados por vírgula
decada
number
optional
Para tipo='ranking': Década do ranking (ex: 1990, 2000, 2010)
sexo
string
optional
Filtrar por sexo: M (masculino) ou F (feminino)
localidade
string
optional
Código IBGE da localidade (UF: 2 dígitos, Município: 7 dígitos)
limite
number
optional
Para tipo='ranking': Número de nomes (padrão: 20)
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"type": "string",
"enum": [
"frequencia",
"ranking"
],
"description": "Tipo de consulta: 'frequencia' para buscar nomes específicos ou 'ranking' para ver os mais populares"
},
"nomes": {
"description": "Para tipo='frequencia': Nome ou nomes separados por vírgula",
"type": "string"
},
"decada": {
"description": "Para tipo='ranking': Década do ranking (ex: 1990, 2000, 2010)",
"type": "number"
},
"sexo": {
"description": "Filtrar por sexo: M (masculino) ou F (feminino)",
"type": "string",
"enum": [
"M",
"F"
]
},
"localidade": {
"description": "Código IBGE da localidade (UF: 2 dígitos, Município: 7 dígitos)",
"type": "string"
},
"limite": {
"default": 20,
"description": "Para tipo='ranking': Número de nomes (padrão: 20)",
"type": "number",
"minimum": 1,
"maximum": 100
}
},
"required": [
"tipo"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_noticias
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.
Parameters7
busca
string
optional
Termo para buscar nas notícias
quantidade
number
optional
Quantidade de notícias a retornar (padrão: 10, máximo: 100)
pagina
number
optional
Número da página para paginação
de
string
optional
Data inicial no formato DD/MM/AAAA (ex: 01/01/2024)
ate
string
optional
Data final no formato DD/MM/AAAA (ex: 31/12/2024)
tipo
string
optional
Tipo de publicação: 'release' ou 'noticia'
destaque
boolean
optional
Filtrar apenas notícias em destaque
Raw schema
{
"type": "object",
"properties": {
"busca": {
"description": "Termo para buscar nas notícias",
"type": "string"
},
"quantidade": {
"default": 10,
"description": "Quantidade de notícias a retornar (padrão: 10, máximo: 100)",
"type": "number",
"minimum": 1,
"maximum": 100
},
"pagina": {
"default": 1,
"description": "Número da página para paginação",
"type": "number",
"minimum": 1
},
"de": {
"description": "Data inicial no formato DD/MM/AAAA (ex: 01/01/2024)",
"type": "string"
},
"ate": {
"description": "Data final no formato DD/MM/AAAA (ex: 31/12/2024)",
"type": "string"
},
"tipo": {
"description": "Tipo de publicação: 'release' ou 'noticia'",
"type": "string",
"enum": [
"release",
"noticia"
]
},
"destaque": {
"description": "Filtrar apenas notícias em destaque",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_sidra_tabelas
Lists and searches available SIDRA tables.
Features:
- List all SIDRA tables (aggregates)
- Search by table name
- 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.
Parameters3
busca
string
optional
Termo para buscar no nome das tabelas/agregados
pesquisa
string
optional
Filtrar por código ou nome da pesquisa (ex: 'censo', 'pnad', 'pib')
limite
number
optional
Número máximo de resultados (padrão: 20)
Raw schema
{
"type": "object",
"properties": {
"busca": {
"description": "Termo para buscar no nome das tabelas/agregados",
"type": "string"
},
"pesquisa": {
"description": "Filtrar por código ou nome da pesquisa (ex: 'censo', 'pnad', 'pib')",
"type": "string"
},
"limite": {
"default": 20,
"description": "Número máximo de resultados (padrão: 20)",
"type": "number",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_sidra_metadados
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.
Parameters3
tabela
string
required
Código da tabela/agregado SIDRA (ex: '6579', '9514', '4714')
incluir_periodos
boolean
optional
Incluir lista de períodos disponíveis (padrão: true)
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).
Parameters6
localidade
string
required
Código IBGE ou sigla da localidade (ex: 'BR', 'SP', '35', '3550308')
tipo
string
optional
Tipo de divisão territorial
formato
string
optional
Formato de saída (padrão: geojson)
resolucao
string
optional
Resolução/divisões internas:
0 = Sem divisões internas
1 = Macrorregiões (apenas para BR)
2 = Unidades da Federação
3 = Mesorregiões
4 = Microrregiões
5 = Municípios
qualidade
string
optional
Qualidade do traçado: 1=mínima, 2=baixa, 3=intermediária, 4=máxima
intrarregiao
string
optional
Código de região para filtrar (apenas quando localidade=BR)
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.
Parameters2
busca
string
optional
Termo para buscar no nome ou ID da pesquisa
detalhes
string
optional
Código da pesquisa para ver detalhes e tabelas disponíveis
Raw schema
{
"type": "object",
"properties": {
"busca": {
"description": "Termo para buscar no nome ou ID da pesquisa",
"type": "string"
},
"detalhes": {
"description": "Código da pesquisa para ver detalhes e tabelas disponíveis",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_censo
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="<column label>" 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.
Parameters9
ano
string
optional
Ano do censo (1970, 1980, 1991, 2000, 2010, 2022) ou 'todos' para série histórica
tema
string
optional
Tema dos dados:
- populacao: População residente
- alfabetizacao: Taxa de alfabetização
- domicilios: Características dos domicílios
- idade_sexo: Pirâmide etária
- religiao: Distribuição por religião
- cor_raca: Cor ou raça
- rendimento: Rendimento mensal
- migracao: Migração
- educacao: Nível de instrução
- trabalho: Ocupação e trabalho
- indigenas: População indígena
- quilombolas: População quilombola
- saneamento: Abastecimento de água e esgoto
- deficiencia: Pessoas com deficiência
- nupcialidade: Estado civil
- fecundidade: Taxa de fecundidade
- listar: Lista tabelas disponíveis
nivel_territorial
string
optional
Nível territorial (código N): 1=Brasil, 2=Região, 3=UF, 6=Município
localidades
string
optional
Códigos das localidades ou 'all'
formato
string
optional
Formato de saída
campos
string
optional
Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta.
estatisticas
boolean
optional
Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato
agruparPor
string
optional
Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)
Raw schema
{
"type": "object",
"properties": {
"ano": {
"description": "Ano do censo (1970, 1980, 1991, 2000, 2010, 2022) ou 'todos' para série histórica",
"type": "string",
"enum": [
"1970",
"1980",
"1991",
"2000",
"2010",
"2022",
"todos"
]
},
"tema": {
"default": "populacao",
"description": "Tema dos dados:\n- populacao: População residente\n- alfabetizacao: Taxa de alfabetização\n- domicilios: Características dos domicílios\n- idade_sexo: Pirâmide etária\n- religiao: Distribuição por religião\n- cor_raca: Cor ou raça\n- rendimento: Rendimento mensal\n- migracao: Migração\n- educacao: Nível de instrução\n- trabalho: Ocupação e trabalho\n- indigenas: População indígena\n- quilombolas: População quilombola\n- saneamento: Abastecimento de água e esgoto\n- deficiencia: Pessoas com deficiência\n- nupcialidade: Estado civil\n- fecundidade: Taxa de fecundidade\n- listar: Lista tabelas disponíveis",
"type": "string",
"enum": [
"populacao",
"alfabetizacao",
"domicilios",
"idade_sexo",
"religiao",
"cor_raca",
"rendimento",
"migracao",
"educacao",
"trabalho",
"indigenas",
"quilombolas",
"saneamento",
"deficiencia",
"nupcialidade",
"fecundidade",
"listar"
]
},
"nivel_territorial": {
"default": "1",
"description": "Nível territorial (código N): 1=Brasil, 2=Região, 3=UF, 6=Município",
"type": "string"
},
"localidades": {
"default": "all",
"description": "Códigos das localidades ou 'all'",
"type": "string"
},
"formato": {
"default": "tabela",
"description": "Formato de saída",
"type": "string",
"enum": [
"tabela",
"json"
]
},
"campos": {
"description": "Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta.",
"type": "string"
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato",
"type": "boolean"
},
"agruparPor": {
"description": "Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição",
"type": "string"
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_indicadores
Queries IBGE economic and social indicators.
Available indicators:
**Economic:**
- pib: GDP at current prices
- pib_variacao: GDP variation (%)
- pib_per_capita: GDP per capita
- industria: Industrial production
- comercio: Retail sales
- servicos: Services volume
**Prices:**
- ipca: Monthly IPCA
- ipca_acumulado: 12-month IPCA
- inpc: Monthly INPC
**Labor:**
- desemprego: Unemployment rate
- ocupacao: Employed people
- rendimento: Average income
- 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"
Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which state has the highest unemployment?", "median GDP per capita across states") use estatisticas=true — full distribution + top/bottom over ALL rows before truncation; agruparPor="<column label>" (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.
Parameters10
indicador
string
optional
Nome do indicador (ex: "pib", "ipca", "desemprego", "populacao").
Use "listar" para ver todos os indicadores disponíveis.
categoria
string
optional
Filtrar por categoria de indicadores
nivel_territorial
string
optional
Nível territorial (código N): 1=Brasil, 2=Região, 3=UF
localidades
string
optional
Códigos das localidades ou 'all'
periodos
string
optional
Períodos (ex: '2023', 'last', 'last 4')
formato
string
optional
Formato de saída
campos
string
optional
Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta.
estatisticas
boolean
optional
Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato
agruparPor
string
optional
Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)
Raw schema
{
"type": "object",
"properties": {
"indicador": {
"description": "Nome do indicador (ex: \"pib\", \"ipca\", \"desemprego\", \"populacao\").\nUse \"listar\" para ver todos os indicadores disponíveis.",
"type": "string"
},
"categoria": {
"description": "Filtrar por categoria de indicadores",
"type": "string",
"enum": [
"economico",
"precos",
"trabalho",
"populacao",
"agropecuaria",
"todos"
]
},
"nivel_territorial": {
"default": "1",
"description": "Nível territorial (código N): 1=Brasil, 2=Região, 3=UF",
"type": "string"
},
"localidades": {
"default": "all",
"description": "Códigos das localidades ou 'all'",
"type": "string"
},
"periodos": {
"default": "last",
"description": "Períodos (ex: '2023', 'last', 'last 4')",
"type": "string"
},
"formato": {
"default": "tabela",
"description": "Formato de saída",
"type": "string",
"enum": [
"tabela",
"json"
]
},
"campos": {
"description": "Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta.",
"type": "string"
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato",
"type": "boolean"
},
"agruparPor": {
"description": "Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição",
"type": "string"
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_cnae
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.
Parameters4
codigo
string
optional
Código CNAE para buscar (seção, divisão, grupo, classe ou subclasse).
Exemplos:
- Seção: "A" (agricultura)
- Divisão: "01" (agricultura e pecuária)
- Grupo: "01.1" (produção de lavouras)
- Classe: "01.11" (cultivo de cereais)
- Subclasse: "0111-3/01" (cultivo de arroz)
busca
string
optional
Termo para buscar na descrição das atividades (ex: 'software', 'restaurante', 'comércio')
nivel
string
optional
Nível hierárquico para listar (padrão: mostra todos os níveis relevantes)
limite
number
optional
Número máximo de resultados (padrão: 20)
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"description": "Código CNAE para buscar (seção, divisão, grupo, classe ou subclasse).\nExemplos:\n- Seção: \"A\" (agricultura)\n- Divisão: \"01\" (agricultura e pecuária)\n- Grupo: \"01.1\" (produção de lavouras)\n- Classe: \"01.11\" (cultivo de cereais)\n- Subclasse: \"0111-3/01\" (cultivo de arroz)",
"type": "string"
},
"busca": {
"description": "Termo para buscar na descrição das atividades (ex: 'software', 'restaurante', 'comércio')",
"type": "string"
},
"nivel": {
"description": "Nível hierárquico para listar (padrão: mostra todos os níveis relevantes)",
"type": "string",
"enum": [
"secoes",
"divisoes",
"grupos",
"classes",
"subclasses"
]
},
"limite": {
"default": 20,
"description": "Número máximo de resultados (padrão: 20)",
"type": "number"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_geocodigo
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.
Parameters3
codigo
string
optional
Código IBGE para decodificar.
Formatos aceitos:
- 1 dígito: Região (1-5)
- 2 dígitos: UF (11-53)
- 7 dígitos: Município
- 9 dígitos: Distrito
nome
string
optional
Nome da localidade para encontrar o código IBGE (estado ou município)
uf
string
optional
Estado por sigla (SP), nome (São Paulo) ou código IBGE (35) para restringir a busca por nome de município
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"description": "Código IBGE para decodificar.\nFormatos aceitos:\n- 1 dígito: Região (1-5)\n- 2 dígitos: UF (11-53)\n- 7 dígitos: Município\n- 9 dígitos: Distrito",
"type": "string"
},
"nome": {
"description": "Nome da localidade para encontrar o código IBGE (estado ou município)",
"type": "string"
},
"uf": {
"description": "Estado por sigla (SP), nome (São Paulo) ou código IBGE (35) para restringir a busca por nome de município",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_calendario
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.
Parameters6
de
string
optional
Data inicial no formato DD/MM/AAAA (ex: '01/01/2024')
ate
string
optional
Data final no formato DD/MM/AAAA (ex: '31/12/2024')
produto
string
optional
Filtrar por produto/pesquisa (ex: 'IPCA', 'PNAD', 'PIB')
tipo
string
optional
Tipo de evento: 'divulgacao' (publicações), 'coleta' (pesquisas de campo), ou 'todos'
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.
Parameters3
localidades
string
required
Códigos IBGE das localidades separados por vírgula (ex: "3550308,3304557,4106902").
Use 7 dígitos para municípios, 2 dígitos para UFs.
indicador
string
optional
Indicador para comparação:
- populacao: Estimativa populacional atual
- populacao_censo: População do Censo 2022
- pib: PIB a preços correntes (Mil Reais)
- area: Área territorial (km²)
- densidade: Densidade demográfica (hab/km²)
- alfabetizacao: Taxa de alfabetização
- domicilios: Número de domicílios
- listar: Lista indicadores disponíveis
formato
string
optional
Formato de saída: tabela, json ou ranking (ordenado)
Raw schema
{
"type": "object",
"properties": {
"localidades": {
"type": "string",
"description": "Códigos IBGE das localidades separados por vírgula (ex: \"3550308,3304557,4106902\").\nUse 7 dígitos para municípios, 2 dígitos para UFs."
},
"indicador": {
"default": "populacao",
"description": "Indicador para comparação:\n- populacao: Estimativa populacional atual\n- populacao_censo: População do Censo 2022\n- pib: PIB a preços correntes (Mil Reais)\n- area: Área territorial (km²)\n- densidade: Densidade demográfica (hab/km²)\n- alfabetizacao: Taxa de alfabetização\n- domicilios: Número de domicílios\n- listar: Lista indicadores disponíveis",
"type": "string",
"enum": [
"populacao",
"populacao_censo",
"pib",
"area",
"densidade",
"alfabetizacao",
"domicilios",
"listar"
]
},
"formato": {
"default": "tabela",
"description": "Formato de saída: tabela, json ou ranking (ordenado)",
"type": "string",
"enum": [
"tabela",
"json",
"ranking"
]
}
},
"required": [
"localidades"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_malhas_tema
Gets thematic geographic meshes from IBGE.
Available themes:
- biomas: Brazilian biomes (Amazon, Cerrado, Atlantic Forest, Caatinga, Pampa, Pantanal)
- amazonia_legal: Legal Amazon area
- semiarido: Semi-arid region
- costeiro: Coastal zone
- fronteira: Border strip
- metropolitana: Metropolitan regions
- ride: Integrated Development Regions
Biome codes:
- 1: Amazon
- 2: Cerrado
- 3: Atlantic Forest
- 4: Caatinga
- 5: Pampa
- 6: Pantanal
Examples:
- All biomes: tema="biomas"
- Amazon biome: tema="biomas", codigo="1"
- Legal Amazon: tema="amazonia_legal"
- Metropolitan regions: tema="metropolitana"
- With municipalities: tema="biomas", resolucao="5"
- List themes: tema="listar"
Use a different tool when:
- Administrative meshes (Brazil/region/state/municipality outlines) → ibge_malhas
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).
Parameters5
tema
string
required
Tema da malha:
- biomas: Biomas brasileiros (Amazônia, Cerrado, etc.)
- amazonia_legal: Área da Amazônia Legal
- semiarido: Região do semiárido
- costeiro: Zona costeira
- fronteira: Faixa de fronteira
- metropolitana: Regiões metropolitanas
- ride: Regiões Integradas de Desenvolvimento
- listar: Lista temas disponíveis
codigo
string
optional
Código específico do tema (ex: código do bioma, da região metropolitana)
formato
string
optional
Formato de saída
resolucao
string
optional
0 = Apenas contorno, 5 = Com municípios
qualidade
string
optional
Qualidade do traçado: 1=mínima, 4=máxima
Raw schema
{
"type": "object",
"properties": {
"tema": {
"type": "string",
"enum": [
"biomas",
"amazonia_legal",
"semiarido",
"costeiro",
"fronteira",
"metropolitana",
"ride",
"listar"
],
"description": "Tema da malha:\n- biomas: Biomas brasileiros (Amazônia, Cerrado, etc.)\n- amazonia_legal: Área da Amazônia Legal\n- semiarido: Região do semiárido\n- costeiro: Zona costeira\n- fronteira: Faixa de fronteira\n- metropolitana: Regiões metropolitanas\n- ride: Regiões Integradas de Desenvolvimento\n- listar: Lista temas disponíveis"
},
"codigo": {
"description": "Código específico do tema (ex: código do bioma, da região metropolitana)",
"type": "string"
},
"formato": {
"default": "geojson",
"description": "Formato de saída",
"type": "string",
"enum": [
"geojson",
"topojson",
"svg"
]
},
"resolucao": {
"default": "0",
"description": "0 = Apenas contorno, 5 = Com municípios",
"type": "string",
"enum": [
"0",
"5"
]
},
"qualidade": {
"default": "4",
"description": "Qualidade do traçado: 1=mínima, 4=máxima",
"type": "string",
"enum": [
"1",
"2",
"3",
"4"
]
}
},
"required": [
"tema"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_vizinhos
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.
Parameters4
municipio
string
required
Código IBGE do município (7 dígitos) ou nome do município
uf
string
optional
Estado por sigla (SP), nome (São Paulo) ou código IBGE (35) — obrigatório se usar nome do município
raio
number
optional
Raio em km para buscar municípios próximos (usa centróides)
incluir_dados
boolean
optional
Incluir dados populacionais dos vizinhos
Raw schema
{
"type": "object",
"properties": {
"municipio": {
"type": "string",
"description": "Código IBGE do município (7 dígitos) ou nome do município"
},
"uf": {
"description": "Estado por sigla (SP), nome (São Paulo) ou código IBGE (35) — obrigatório se usar nome do município",
"type": "string"
},
"raio": {
"description": "Raio em km para buscar municípios próximos (usa centróides)",
"type": "number"
},
"incluir_dados": {
"default": false,
"description": "Incluir dados populacionais dos vizinhos",
"type": "boolean"
}
},
"required": [
"municipio"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_datasaude
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="<column label>" 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.
Parameters9
indicador
string
required
Indicador de saúde. Disponíveis:
- mortalidade_infantil: Taxa de mortalidade infantil
- esperanca_vida: Esperança de vida ao nascer
- nascidos_vivos: Nascidos vivos
- obitos: Óbitos por local de residência
- fecundidade: Taxa de fecundidade
- saneamento_agua: Abastecimento de água
- saneamento_esgoto: Esgotamento sanitário
- plano_saude: Cobertura de plano de saúde
- listar: Lista indicadores disponíveis
nivel_territorial
string
optional
Nível territorial (código N): 1=Brasil, 2=Região, 3=UF, 6=Município
localidade
string
optional
Código da localidade ou 'all'
periodo
string
optional
Período: 'last', 'all', ou ano específico
formato
string
optional
Formato de saída
campos
string
optional
Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta.
estatisticas
boolean
optional
Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato
agruparPor
string
optional
Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)
Raw schema
{
"type": "object",
"properties": {
"indicador": {
"type": "string",
"description": "Indicador de saúde. Disponíveis:\n- mortalidade_infantil: Taxa de mortalidade infantil\n- esperanca_vida: Esperança de vida ao nascer\n- nascidos_vivos: Nascidos vivos\n- obitos: Óbitos por local de residência\n- fecundidade: Taxa de fecundidade\n- saneamento_agua: Abastecimento de água\n- saneamento_esgoto: Esgotamento sanitário\n- plano_saude: Cobertura de plano de saúde\n- listar: Lista indicadores disponíveis"
},
"nivel_territorial": {
"default": "1",
"description": "Nível territorial (código N): 1=Brasil, 2=Região, 3=UF, 6=Município",
"type": "string"
},
"localidade": {
"default": "all",
"description": "Código da localidade ou 'all'",
"type": "string"
},
"periodo": {
"default": "last",
"description": "Período: 'last', 'all', ou ano específico",
"type": "string"
},
"formato": {
"default": "tabela",
"description": "Formato de saída",
"type": "string",
"enum": [
"tabela",
"json"
]
},
"campos": {
"description": "Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta.",
"type": "string"
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato",
"type": "boolean"
},
"agruparPor": {
"description": "Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição",
"type": "string"
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"indicador"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_paises
Queries international country data via IBGE.
Features:
- List all countries (following UN M49 methodology)
- Country details (area, languages, currency, location)
- Search countries by name
- Filter by region/continent
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"
- Search: tipo="buscar", busca="Argentina"
- Americas countries: tipo="listar", regiao="americas"
- Available indicators: tipo="indicadores"
Behavior: read-only and idempotent — a live GET against the public IBGE Países API. Returns Markdown.
Parameters5
tipo
string
optional
Tipo de consulta: listar (todos), detalhes (de um país), indicadores, buscar
pais
string
optional
Código ISO-ALPHA-2 do país (ex: BR, US, AR) ou código M49
busca
string
optional
Termo de busca para filtrar países pelo nome
indicadores
string
optional
IDs dos indicadores separados por | (ex: 77819|77820)
regiao
string
optional
Filtrar por região/continente: americas, europa, africa, asia, oceania
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"default": "listar",
"description": "Tipo de consulta: listar (todos), detalhes (de um país), indicadores, buscar",
"type": "string",
"enum": [
"listar",
"detalhes",
"indicadores",
"buscar"
]
},
"pais": {
"description": "Código ISO-ALPHA-2 do país (ex: BR, US, AR) ou código M49",
"type": "string"
},
"busca": {
"description": "Termo de busca para filtrar países pelo nome",
"type": "string"
},
"indicadores": {
"description": "IDs dos indicadores separados por | (ex: 77819|77820)",
"type": "string"
},
"regiao": {
"description": "Filtrar por região/continente: americas, europa, africa, asia, oceania",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
ibge_cidades
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.
Parameters5
tipo
string
optional
Tipo de consulta: panorama (resumo geral), indicador (específico), pesquisas (listar), historico
municipio
string
optional
Código IBGE do município (7 dígitos)
uf
string
optional
Código ou sigla da UF para filtrar (ex: 35 ou SP)
indicador
string
optional
ID do indicador ou nome para busca
pesquisa
string
optional
ID da pesquisa para filtrar indicadores
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"default": "panorama",
"description": "Tipo de consulta: panorama (resumo geral), indicador (específico), pesquisas (listar), historico",
"type": "string",
"enum": [
"panorama",
"indicador",
"pesquisas",
"historico"
]
},
"municipio": {
"description": "Código IBGE do município (7 dígitos)",
"type": "string"
},
"uf": {
"description": "Código ou sigla da UF para filtrar (ex: 35 ou SP)",
"type": "string"
},
"indicador": {
"description": "ID do indicador ou nome para busca",
"type": "string"
},
"pesquisa": {
"description": "ID da pesquisa para filtrar indicadores",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
search
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.
Parameters1
query
string
required
Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)"
}
},
"required": [
"query"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
fetch
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.
Parameters1
id
string
required
Identificador de um documento devolvido por `search`
Raw schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identificador de um documento devolvido por `search`"
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
Live, exact Brazilian public data for your AI assistant — with provenance, not guesswork.
Ask an LLM "what was Belo Horizonte's population in the 2022 Census?" and you get a plausible number from its training data: maybe right, maybe outdated, with no source. ibge-br-mcp instead has your assistant query the official IBGE APIs in real time — returning the exact figure together with the table and period it came from.
This server implements the Model Context Protocol (MCP) to give AI assistants live, structured access to Brazil's public geographic, demographic, economic, and health data — sourced from the IBGE APIs (including health indicators served through IBGE's SIDRA system).
See it in action
Ask your assistant, in English or Portuguese:
"What was Belo Horizonte's population in the 2022 Census?" → ibge_cidades / ibge_censo
"List the municipalities of Espírito Santo." → ibge_municipios
"Compare GDP across the Southeast state capitals." → ibge_comparar
The answers come live from the official IBGE APIs — exact figures with the table and period they came from, not numbers guessed from training data.
Want to see a whole analysis rather than a single answer? The
end-to-end demo works one real question — which state grew
most between the 2010 and 2022 Censuses, and what drove it — from first call to
conclusion, with every figure as it came back. The
practical examples are seven shorter recipes, including
ranking all 5,570 municipalities in a single call.
Features
21 specialized tools covering all major IBGE data domains
Provenance block on every response — source, canonical URL, reference
period, real extraction timestamp, ready-to-use citation, and legal regime
(see Data provenance)
565 automated tests — 88% overall coverage, 92% across the tools
Automatic caching with configurable TTL for optimal performance
Retry mechanism with exponential backoff for network resilience
Comprehensive validation for all input parameters
Standardized error handling with helpful suggestions
Full TypeScript support with strict typing
Data provenance
Since v3.3.0 every successful tool response carries a provenance block
(portfolio contract v1.0),
so each number is citable, auditable, and reproducible. The block is emitted on
three channels:
structuredContent.provenance (parseable, visible to the model) — exactly
six keys: source (the IBGE API queried), source_url (canonical URL that
reproduces the query), data_vintage (reference period when the source
exposes one; null otherwise), retrieved_at (the REAL upstream extraction
instant, preserved across cache hits, Brasília time), citation
("Fonte: IBGE — [pesquisa/tabela], [URL], extraído em [data]."), and
license — plus attribution, the canonical list of source URLs.
_meta under br.com.sidneybissoli.ibge/provenance and .../attribution
(out-of-band mirror for audit/UI, zero model tokens).
A compact text footer appended to the Markdown, for text-only clients.
The IBGE APIs declare no license of their own; the legal regime is Brazil's
open-data framework — Lei 12.527/2011 (LAI) and Decreto 8.777/2016
(unrestricted reuse, free use, obligation limited to crediting the source).
Statistics-mode responses (estatisticas=true) and ibge_comparar are marked
derived with an explanatory note in the canonical block, since the
aggregates are computed server-side from the raw IBGE values.
Available Tools
Localities & Geography
Tool
Description
ibge_estados
List Brazilian states with region filtering
ibge_municipios
List municipalities by state or search by name
ibge_localidade
Get details of a locality by IBGE code
ibge_geocodigo
Decode IBGE codes or search codes by name
ibge_vizinhos
Find neighboring municipalities
Statistical Data (SIDRA)
Tool
Description
ibge_sidra
Query SIDRA tables (Census, PNAD, GDP, etc.)
ibge_sidra_tabelas
List and search available SIDRA tables
ibge_sidra_metadados
Get table metadata (variables, periods, levels)
ibge_pesquisas
List IBGE research surveys and their tables
Economic & Social Indicators
Tool
Description
ibge_indicadores
Economic and social indicators (GDP, IPCA, unemployment)
ibge_censo
Census data (1970-2022) with 16 themes
ibge_comparar
Compare indicators across localities with rankings
Municipal Data (Cidades@)
Tool
Description
ibge_cidades
Municipal indicators (population, HDI, GDP per capita, etc.)
International Data
Tool
Description
ibge_paises
Country data following UN M49 methodology
Demographics
Tool
Description
ibge_nomes
Name frequency and rankings in Brazil
Classifications
Tool
Description
ibge_cnae
CNAE (National Classification of Economic Activities)
Maps & Geographic Meshes
Tool
Description
ibge_malhas
Geographic meshes (GeoJSON, TopoJSON, SVG)
ibge_malhas_tema
Thematic meshes (biomes, Legal Amazon, semi-arid)
Health
Tool
Description
ibge_datasaude
Health indicators via IBGE's SIDRA
News & Calendar
Tool
Description
ibge_noticias
IBGE news and press releases
ibge_calendario
IBGE release and collection calendar
Which tool should I use?
With 21 tools, several can touch the same topic. Quick guide for the common overlaps:
Population & demographics
You want…
Use
A single municipality/state panel (population, HDI, GDP…)
ibge_cidades
Census data or historical series (1970–2022)
ibge_censo
Rank/compare 2–10 localities on one indicator
ibge_comparar
A macro indicator time series (GDP, IPCA, unemployment…)
ibge_indicadores
A specific SIDRA table / fine control
ibge_sidra
The largest/smallest/mean/median across a whole table
ibge_sidra/ibge_censo/ibge_indicadores/ibge_datasaude with estatisticas=true
# List all states
ibge_estados
# States in Northeast region
ibge_estados(regiao="NE")
# States sorted by abbreviation
ibge_estados(ordenar="sigla")
ibge_municipios
List Brazilian municipalities.
code
# Municipalities of São Paulo state
ibge_municipios(uf="SP")
# Search municipalities by name
ibge_municipios(busca="Campinas")
# Municipalities in MG containing "Belo"
ibge_municipios(uf="MG", busca="Belo")
ibge_cidades
Query municipal indicators (similar to Cidades@ portal).
code
# Panorama of São Paulo
ibge_cidades(tipo="panorama", municipio="3550308")
# Population history
ibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")
# List available research
ibge_cidades(tipo="pesquisas")
# List all countries
ibge_paises(tipo="listar")
# Brazil details
ibge_paises(tipo="detalhes", pais="BR")
# Search countries
ibge_paises(tipo="buscar", busca="Argentina")
# Countries in Americas
ibge_paises(tipo="listar", regiao="americas")
# Brazil population in 2023
ibge_sidra(tabela="6579", periodos="2023")
# Population by state
ibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")
# Census 2022 for São Paulo municipality
ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")
Common tables:
Code
Description
6579
Population estimates (annual)
9514
Census 2022 population
4714
Unemployment rate (PNAD)
6706
GDP at current prices
Territorial levels:
Code
Level
1
Brazil
2
Region (North, Northeast, etc.)
3
State (UF)
6
Municipality
7
Metropolitan Region
106
Health Region
127
Legal Amazon
128
Semi-arid
Statistics mode (also on ibge_censo, ibge_indicadores, ibge_datasaude):
for largest/smallest/mean/median/distribution/ranking questions, pass
estatisticas=true — the server computes the full distribution (min/max/mean/
median/std-dev/labeled percentiles) over all rows before pagination and
returns top/bottom rankings (topN, default 10). agruparPor="<column label>" ranks groups by descending sum, each with its own mini-distribution.
code
# Which state has the largest estimated population?
ibge_sidra(tabela="6579", nivel_territorial="3", estatisticas=true)
# Census 2022 population distribution grouped by state
ibge_censo(ano="2022", tema="populacao", nivel_territorial="3", estatisticas=true, agruparPor="Unidade da Federação")
ibge_censo
Query Census data (1970-2022).
code
# Population Census 2022
ibge_censo(ano="2022", tema="populacao")
# Historical population series
ibge_censo(ano="todos", tema="populacao")
# Literacy by state in 2010
ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")
Available themes: populacao, alfabetizacao, domicilios, idade_sexo, religiao, cor_raca, rendimento, migracao, educacao, trabalho
ibge_indicadores
Query economic and social indicators.
code
# GDP
ibge_indicadores(indicador="pib")
# IPCA last 12 months
ibge_indicadores(indicador="ipca", periodos="last 12")
# Unemployment by state
ibge_indicadores(indicador="desemprego", nivel_territorial="3")
# List all indicators
ibge_indicadores(indicador="listar")
# Frequency of "Maria"
ibge_nomes(tipo="frequencia", nomes="Maria")
# Compare names
ibge_nomes(tipo="frequencia", nomes="João,José,Pedro")
# Ranking of names in 2000s
ibge_nomes(tipo="ranking", decada=2000)
# Female names ranking
ibge_nomes(tipo="ranking", sexo="F")
ibge_malhas
Get geographic meshes (maps).
code
# Brazil with states
ibge_malhas(localidade="BR", resolucao="2")
# São Paulo with municipalities
ibge_malhas(localidade="SP", resolucao="5")
# Specific municipality
ibge_malhas(localidade="3550308")
# SVG format
ibge_malhas(localidade="BR", formato="svg")
Resolution levels:
Value
Internal Divisions
0
No divisions (outline only)
2
States
5
Municipalities
ibge_datasaude
Query Brazilian health indicators served through IBGE's SIDRA (some originally produced by DataSUS, e.g. mortality and births).
code
# Infant mortality in Brazil
ibge_datasaude(indicador="mortalidade_infantil")
# Life expectancy by state
ibge_datasaude(indicador="esperanca_vida", nivel_territorial="3")
# List indicators
ibge_datasaude(indicador="listar")
Available indicators: mortalidade_infantil, esperanca_vida, nascidos_vivos, obitos, fecundidade, saneamento_agua, saneamento_esgoto, plano_saude
# Build
npm run build
# Watch mode
npm run watch
# Run tests
npm test# Run tests in watch mode
npm run test:watch
# Lint
npm run lint
# Format
npm run format
# Test with MCP inspector
npm run inspector
