How do I use mcp-ibge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by FilipePessoa30

Overview Schema Related Servers Score Discussions

Python

Hybrid

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 com pydantic, cache opcional em memória.
✅ Roda 100% local, via stdio — pronto para Claude Desktop, Cursor e outros clientes MCP.

Sumário

Related MCP server: BCB 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-ibge

Isso 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.py

Transporte 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-ibge

Tools disponíveis

Localidades

Tool	Descrição
`listar_regioes`	Lista as 5 grandes regiões do Brasil.
`listar_estados`	Lista os 26 estados + DF, com filtro opcional por região.
`obter_estado`	Detalhes de um estado por sigla (`SP`) ou ID IBGE (`35`).
`listar_municipios`	Lista municípios, opcionalmente filtrados por UF.
`obter_municipio`	Detalhes de um município pelo código IBGE (7 dígitos).
`buscar_municipios_por_nome`	Busca municípios por nome (ignora acentos/maiúsculas) — útil para descobrir o código IBGE.

Agregados / SIDRA

Tool	Descrição
`listar_agregados`	Lista tabelas/agregados do SIDRA, com filtros por pesquisa, assunto ou texto.
`obter_metadados_agregado`	Metadados de um agregado: variáveis, períodos e níveis territoriais disponíveis.
`consultar_dados_agregado`	Consulta valores de um agregado para variáveis, períodos e localidades específicas.

População

Tool	Descrição
`obter_populacao_municipio`	População residente estimada mais recente de um município (agregado SIDRA 6579).
`obter_projecao_populacao`	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
`MCP_IBGE_TIMEOUT`	`15`	Timeout (segundos) para cada requisição HTTP às APIs do IBGE.
`MCP_IBGE_CACHE_ENABLED`	`true`	Habilita/desabilita o cache em memória (`false`/`0`/`no` para desabilitar).
`MCP_IBGE_CACHE_TTL`	`3600`	Tempo de vida (segundos) das entradas em cache.
`MCP_IBGE_CACHE_MAX_SIZE`	`256`	Número máximo de respostas em cache simultaneamente.
`MCP_IBGE_LOG_LEVEL`	`INFO`	Nível de log (`DEBUG`, `INFO`, `WARNING`, ...). Logs sempre vão para stderr.
`MCP_IBGE_TRANSPORT`	`stdio`	Transporte MCP (`stdio` ou `streamable-http`).

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-ibge

e 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 pytest

Estrutura 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_agregado espelha a sintaxe da API SIDRA (parâmetros periodos e localidades); use obter_metadados_agregado para descobrir os IDs válidos de variáveis, períodos e níveis territoriais de cada agregado.

Licença

MIT

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FilipePessoa30/mcp-ibge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server