mcp-ibge
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ibge find the IBGE code for Brasília"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-ibge
Servidor MCP (Model Context Protocol) que expõe dados públicos e oficiais do IBGE (Instituto Brasileiro de Geografia e Estatística) como tools prontas para uso por LLMs e agentes: localidades (regiões, estados, municípios e seus códigos), agregados estatísticos do SIDRA e indicadores de população.
✅ 100% gratuito, sem chave de API.
✅ Dados oficiais via servicodados.ibge.gov.br.
✅ Toda resposta inclui metadados de fonte e rastreabilidade (
source_name,source_url,retrieved_at,endpoint,params).✅ Async (
httpx), validação compydantic, cache opcional em memória.✅ Roda 100% local, via stdio — pronto para Claude Desktop, Cursor e outros clientes MCP.
Sumário
Related MCP server: Banco Central do Brasil (BCB) — SGS MCP
Instalação
Requer Python 3.11+. Recomenda-se uv.
git clone https://github.com/your-username/mcp-ibge.git
cd mcp-ibge
# Cria o ambiente virtual e instala o projeto + dependências de desenvolvimento
uv venv
uv pip install -e ".[dev]"Alternativa com pip:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"Executando o servidor
Diretamente (stdio)
uv run mcp-ibgeIsso inicia o servidor MCP usando o transporte stdio (entrada/saída padrão), o modo recomendado para integração com Claude Desktop, Cursor e outros clientes MCP locais. Logs vão para stderr — stdout é reservado exclusivamente para o protocolo MCP.
Modo de desenvolvimento (MCP Inspector)
O pacote mcp[cli] traz o MCP Inspector,
útil para testar as tools interativamente:
uv run mcp dev src/mcp_ibge/server.pyTransporte alternativo (preparado para o futuro)
O transporte padrão é stdio, mas o servidor já está preparado para rodar
com streamable-http (útil para expor o servidor via rede/Docker/Open
WebUI), bastando definir a variável de ambiente:
export MCP_IBGE_TRANSPORT=streamable-http
uv run mcp-ibgeTools disponíveis
Localidades
Tool | Descrição |
| Lista as 5 grandes regiões do Brasil. |
| Lista os 26 estados + DF, com filtro opcional por região. |
| Detalhes de um estado por sigla ( |
| Lista municípios, opcionalmente filtrados por UF. |
| Detalhes de um município pelo código IBGE (7 dígitos). |
| Busca municípios por nome (ignora acentos/maiúsculas) — útil para descobrir o código IBGE. |
Agregados / SIDRA
Tool | Descrição |
| Lista tabelas/agregados do SIDRA, com filtros por pesquisa, assunto ou texto. |
| Metadados de um agregado: variáveis, períodos e níveis territoriais disponíveis. |
| Consulta valores de um agregado para variáveis, períodos e localidades específicas. |
População
Tool | Descrição |
| População residente estimada mais recente de um município (agregado SIDRA 6579). |
| Projeção populacional do IBGE para o Brasil ou uma UF. |
Exemplos de uso
1. Descobrir o código IBGE de um município
// Chamada
buscar_municipios_por_nome(nome="Florianópolis")
// Resposta (resumida)
{
"metadata": {
"source_name": "IBGE - Instituto Brasileiro de Geografia e Estatística",
"source_url": "https://servicodados.ibge.gov.br/api/v1/localidades/municipios",
"retrieved_at": "2026-06-10T12:00:00+00:00",
"endpoint": "https://servicodados.ibge.gov.br/api/v1/localidades/municipios",
"params": {"nome": "Florianópolis", "limit": 20}
},
"data": [
{
"id": 4205407,
"nome": "Florianópolis",
"microrregiao": { "...": "..." }
}
]
}2. População estimada de um município
// Chamada
obter_populacao_municipio(codigo_municipio="4205407")
// Resposta (resumida)
{
"metadata": {
"source_name": "IBGE - Instituto Brasileiro de Geografia e Estatística",
"source_url": "https://servicodados.ibge.gov.br/api/v3/agregados/6579/periodos/-1/variaveis/9324",
"retrieved_at": "2026-06-10T12:00:01+00:00",
"endpoint": "https://servicodados.ibge.gov.br/api/v3/agregados/6579/periodos/-1/variaveis/9324",
"params": {"codigo_municipio": "4205407", "localidades": "N6[4205407]"}
},
"data": [
{
"id": "9324",
"variavel": "População residente estimada",
"unidade": "Pessoas",
"resultados": [
{
"series": [
{
"localidade": {"id": "4205407", "nome": "Florianópolis"},
"serie": {"2024": "537062"}
}
]
}
]
}
]
}3. Consultar um agregado do SIDRA para todos os estados
consultar_dados_agregado(
agregado_id=6579,
variaveis="9324",
periodos="-1",
localidades="N3[all]"
)Formato das respostas
Toda tool retorna um objeto JSON com dois campos:
Sucesso:
{"metadata": {...}, "data": ...}Erro:
{"metadata": {...}, "error": "mensagem de erro"}
O bloco metadata é sempre:
{
"source_name": "IBGE - Instituto Brasileiro de Geografia e Estatística",
"source_url": "https://servicodados.ibge.gov.br/...",
"retrieved_at": "2026-06-10T12:00:00+00:00",
"endpoint": "https://servicodados.ibge.gov.br/...",
"params": { "...": "parâmetros usados na consulta" }
}Isso garante que qualquer dado retornado possa ser rastreado até a fonte oficial, com data/hora da consulta e os parâmetros utilizados.
Configuração (variáveis de ambiente)
Variável | Padrão | Descrição |
|
| Timeout (segundos) para cada requisição HTTP às APIs do IBGE. |
|
| Habilita/desabilita o cache em memória ( |
|
| Tempo de vida (segundos) das entradas em cache. |
|
| Número máximo de respostas em cache simultaneamente. |
|
| Nível de log ( |
|
| Transporte MCP ( |
Integração com clientes MCP
Claude Desktop
Edite o arquivo claude_desktop_config.json (no Windows:
%APPDATA%\Claude\claude_desktop_config.json; no macOS:
~/Library/Application Support/Claude/claude_desktop_config.json) e
adicione:
{
"mcpServers": {
"ibge": {
"command": "uv",
"args": [
"--directory",
"/caminho/absoluto/para/mcp-ibge",
"run",
"mcp-ibge"
]
}
}
}Reinicie o Claude Desktop. As tools listar_estados, obter_municipio,
consultar_dados_agregado etc. ficarão disponíveis nas conversas.
Cursor
Em Settings -> MCP -> Add new MCP Server, ou editando
~/.cursor/mcp.json:
{
"mcpServers": {
"ibge": {
"command": "uv",
"args": [
"--directory",
"/caminho/absoluto/para/mcp-ibge",
"run",
"mcp-ibge"
]
}
}
}Open WebUI / outros clientes baseados em HTTP
Para clientes que falam HTTP em vez de stdio (ex.: Open WebUI via
mcpo), inicie o servidor com o
transporte streamable-http:
MCP_IBGE_TRANSPORT=streamable-http uv run mcp-ibgee aponte o cliente/proxy para o endpoint exposto pelo servidor.
Desenvolvimento
# Lint e formatação
uv run ruff check .
uv run ruff format .
# Testes
uv run pytestEstrutura do projeto
mcp-ibge/
├── src/mcp_ibge/
│ ├── server.py # Definição das tools FastMCP
│ ├── __main__.py # Entrypoint (stdio / streamable-http)
│ ├── config.py # URLs base, timeouts, cache (via env vars)
│ ├── envelope.py # Envelope de resposta com metadados de fonte
│ ├── http_client.py # Cliente HTTP assíncrono com cache e tratamento de erros
│ ├── cache.py # Cache TTL em memória
│ ├── errors.py # Exceções do cliente IBGE
│ └── clients/
│ ├── localidades.py # API de Localidades
│ ├── agregados.py # API de Agregados / SIDRA
│ └── populacao.py # Indicadores de população
└── tests/ # Testes unitários (pytest + respx)Limitações e fontes de dados
Todas as informações são obtidas em tempo real da API de Serviços de Dados do IBGE (
servicodados.ibge.gov.br), que é pública e não requer autenticação.O cache em memória é local ao processo e não persiste entre execuções — serve apenas para evitar chamadas repetidas durante uma mesma sessão.
A tool
consultar_dados_agregadoespelha a sintaxe da API SIDRA (parâmetrosperiodoselocalidades); useobter_metadados_agregadopara descobrir os IDs válidos de variáveis, períodos e níveis territoriais de cada agregado.
Licença
Available Tools
11 toolsbuscar_municipios_por_nomeA
Busca municípios cujo nome contenha o termo informado.
A busca ignora maiúsculas/minúsculas e acentos (ex.: "sao jose" encontra "São José dos Campos"). Útil para descobrir o código IBGE de um município a partir do nome.
Inputs: nome (required), uf, limit. Returns: object
consultar_dados_agregadoA
Consulta valores de um agregado do SIDRA para variáveis, períodos e localidades específicos.
Para descobrir IDs válidos de variáveis, períodos e níveis territoriais,
chame obter_metadados_agregado antes.
Inputs: agregado_id (required), variaveis, periodos, localidades, +1 more. Returns: object
listar_agregadosA
Lista os agregados (tabelas estatísticas) disponíveis no SIDRA.
Use esta tool para descobrir o ID de um agregado antes de chamar
obter_metadados_agregado ou consultar_dados_agregado.
Inputs: pesquisa, assunto, texto. Returns: object
listar_estadosC
Lista os 26 estados e o Distrito Federal, com sigla, nome e região.
Inputs: regiao. Returns: object
listar_municipiosA
Lista municípios brasileiros, opcionalmente filtrados por estado.
Sem o parâmetro uf, retorna todos os ~5570 municípios do Brasil.
Inputs: uf. Returns: object
listar_regioesA
Lista as 5 grandes regiões geográficas do Brasil (Norte, Nordeste, Sudeste, Sul, CO).
Inputs: no named parameters. Returns: object
obter_estadoA
Obtém os detalhes de um estado (UF) brasileiro.
Inputs: uf (required). Returns: object
obter_metadados_agregadoA
Obtém os metadados de um agregado do SIDRA: variáveis, períodos e níveis territoriais.
Use o resultado para escolher os parâmetros de consultar_dados_agregado.
Inputs: agregado_id (required). Returns: object
obter_municipioA
Obtém os detalhes completos de um município pelo código IBGE.
Inputs: codigo (required). Returns: object
obter_populacao_municipioA
Obtém a população residente estimada mais recente de um município.
Baseado no agregado 6579 (Estimativas de população) do SIDRA.
Inputs: codigo_municipio (required). Returns: object
obter_projecao_populacaoB
Obtém a projeção populacional do IBGE para o Brasil ou uma unidade federativa.
Inputs: localidade. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a distinct purpose: searching, listing, or obtaining details for different entities (municipios, estados, regioes, agregados). Even similar population tools (obter_populacao_municipio vs obter_projecao_populacao) differ in scope. No ambiguity.
All tools follow a consistent verb_noun pattern in snake_case using Portuguese verbs (buscar, consultar, listar, obter). The naming style is uniform and predictable.
11 tools is well-scoped for an IBGE data server. It covers geographic entities and SIDRA aggregates without being excessive or insufficient.
The tool surface covers essential CRUD-like operations for geographic data and statistical aggregates. Minor gaps exist (e.g., no direct tool for fetching multiple municipalities by code), but main workflows are supported.
Related MCP Connectors
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
INEGI MCP — Mexico's national statistics office (INEGI) Indicators API.
IBGE (Instituto Brasileiro de Geografia e Estatística) MCP. Brazil's official statistics agency.…
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
Related MCP Servers
- AlicenseAqualityAmaintenanceThis server provides access to IBGE's public APIs, enabling AI assistants to query geographic, demographic, and statistical data from Brazil.23286 npm14MIT
- AlicenseAqualityBmaintenanceMCP server for the Brazilian Central Bank (BCB/SGS) public API, providing access to 18,000+ economic time series. Includes a curated catalog of 150+ popular indicators organized in 12 categories: interest rates (Selic), inflation (IPCA, IGP-M, INPC), exchange rates (USD, EUR), GDP, employment, credit, fiscal data, and more. Supports historical queries with date filters, latest values, metadata loo17295 npm11MIT
- AlicenseAqualityDmaintenanceAn MCP server that connects AI agents to over 200 tools across 27 Brazilian public APIs, covering economic, legislative, transparency, and judicial data. It enables users to query and cross-reference extensive government datasets from sources like IBGE, the Central Bank, and the Brazilian Congress.2271,861MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for accessing IBGE (Brazilian Institute of Geography and Statistics) data, enabling natural language queries via the Pipeworx gateway.145 npmMIT