Skip to main content
Glama

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

Available Tools

11 tools
buscar_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

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    11 tools is well-scoped for an IBGE data server. It covers geographic entities and SIDRA aggregates without being excessive or insufficient.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP 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 loo
      17
      295 npm
      11
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      22
      7
      1,861
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for accessing IBGE (Brazilian Institute of Geography and Statistics) data, enabling natural language queries via the Pipeworx gateway.
      145 npm
      MIT