How do I use mcp-ibge?

1. Click on "Deploy 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 Source Related Servers Discussions Admin

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

ParametersJSON Schema

Name	Required	Description
`nome`	Yes	Termo de busca (ex.: "Sao Jose").
`uf`	No	Restringe a busca aos municípios desta UF (sigla ou ID).
`limit`	No	Número máximo de resultados.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: case and accent insensitivity, and that it returns IBGE codes. It could mention rate limits or result ordering, but the provided info is helpful and accurate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences: first states the core action, second adds behavioral details and a use case. No redundant words; every sentence provides essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema (not shown), so the description need not detail return structure. It covers the input purpose, search behavior, and typical use. Could briefly mention that results are a list of municipalities with codes, but missing that is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the case/accent insensitivity for 'nome', clarifying that 'uf' accepts both sigla and ID, and setting expectations for 'limit'. This exceeds mere repetition of schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches municipalities by name, and explicitly distinguishes its value from siblings by mentioning it helps discover the IBGE code from a name, which is a specific use case not covered by listar_municipios or obter_municipio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a concrete use case (discovering IBGE code from name) and implies when to use this tool over others. However, it does not explicitly state when not to use it or mention alternative tools for other scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`agregado_id`	Yes	ID numérico do agregado do SIDRA.
`variaveis`	No	ID de variável, lista separada por vírgula, ou "all" para todas.	all
`periodos`	No	Período(s): um ano ("2021"), intervalo ("2010-2020"), lista ("2019,2021") ou relativo ("-1" = último período disponível).	-1
`localidades`	No	Unidade territorial no formato N<nivel>[<ids>], ex.: "N1[all]" (Brasil), "N3[all]" (todos os estados), "N6[3550308]" (município de São Paulo). "BR" é aceito como atalho para "N1[all]".	N1[all]
`classificacoes`	No	Filtro opcional de classificação, formato "<id_classificacao>[<id_categoria>]".

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It only states that it queries values but gives no details on behavioral traits such as rate limits, pagination, error handling, or the nature of the returned data. This is insufficient for a tool with five parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, with the first stating the main purpose and the second providing crucial usage guidance. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, the description does not need to explain return values. It covers the main action and the dependency on metadata. However, it could be more specific about what 'valores' means (e.g., census data, economic indicators), but this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description mentions the prerequisite call to metadata but does not add significant new meaning beyond the schema descriptions for the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it queries values of an aggregate for specific variables, periods, and locations. The verb 'consulta' and resource 'agregado do SIDRA' are clear, and it distinguishes from sibling tools like obter_metadados_agregado which are for metadata retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description recommends calling obter_metadados_agregado first to discover valid IDs, providing clear context for proper use. It does not explicitly state when not to use the tool, but the purpose is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`pesquisa`	No	Filtra pelo nome/sigla da pesquisa de origem (ex.: "Censo Demográfico").
`assunto`	No	Filtra pelo nome do assunto (ex.: "População").
`texto`	No	Filtro textual adicional aplicado ao nome dos agregados (substring, sem caixa).

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It correctly implies a read-only, listing operation with optional filters, but it does not mention any limits, pagination, sorting, or default behavior. A 3 is appropriate as the basic nature is clear but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that first state the core function and then provide a critical use-case hint. Every sentence is meaningful and there is no superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a straightforward list tool with an output schema and well-documented parameters, the description adequately covers the essential context. It explains the primary use case and the tool's role in a larger workflow. A small deduction is made because it doesn't hint at the type of data returned (e.g., containing IDs and names), but this is minor given the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for its three optional parameters. The tool description only briefly summarizes the parameters as optional filters without adding new semantic information. Since the schema already carries the details, a baseline of 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states that the tool lists available aggregates (tables) in SIDRA, and it explains that its primary use is to discover the ID before calling related tools like 'obter_metadados_agregado' or 'consultar_dados_agregado'. This clearly distinguishes it from sibling tools that operate on specific aggregates or retrieve other data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use this tool: before calling metadata or data retrieval tools for aggregates. However, it does not explicitly mention when not to use it or discuss alternative tools for other purposes, but the context from sibling tool names helps fill that gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listar_estadosC

Lista os 26 estados e o Distrito Federal, com sigla, nome e região.

ParametersJSON Schema

Name	Required	Description	Default
`regiao`	No	Sigla da grande região ("N", "NE", "CO", "SE", "S") ou ID numérico.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It lists output fields but fails to mention that the 'regiao' parameter is optional and that omitting it returns all states. No mention of ordering, pagination, or limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence that is front-loaded with key information. It is efficient, though it could include more usage context without adding length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity and presence of an output schema, the description is minimally adequate. It misses details about parameter optionality and filtering behavior, leaving the agent to infer from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'regiao', which already explains valid values. The description adds no extra meaning about the parameter beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: lists 26 states and the Federal District with abbreviation, name, and region. It uses a specific verb and resource, distinguishing it from siblings like 'obter_estado' (single state) and 'listar_municipios' (municipalities). However, it does not explicitly contrast with siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs. alternatives like 'listar_regioes' or 'obter_estado'. The description only states what it does, not context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listar_municipiosA

Lista municípios brasileiros, opcionalmente filtrados por estado.

Sem o parâmetro uf, retorna todos os ~5570 municípios do Brasil.

ParametersJSON Schema

Name	Required	Description	Default
`uf`	No	Sigla (ex.: "SP") ou ID IBGE do estado. Se omitido, lista todo o Brasil.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses the default behavior and scale, but lacks details on pagination, rate limits, or sorting. Adequate but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. First sentence states purpose with optional filter; second adds critical scale context. Perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description adequately covers when to use the parameter. It could mention output format briefly, but the output schema compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the parameter description is already good. The description adds value by clarifying the default (all municipalities) and the large result set, earning above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists Brazilian municipalities, optionally filtered by state. It distinguishes from siblings like 'listar_estados' and 'buscar_municipios_por_nome' by its specific function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the effect of omitting the 'uf' parameter (returns all ~5570 municipalities), providing clear context for when to filter. It does not explicitly state when not to use the tool, but the sibling list helps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listar_regioesA

Lista as 5 grandes regiões geográficas do Brasil (Norte, Nordeste, Sudeste, Sul, CO).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It clearly states the tool returns a fixed list of 5 regions, which is sufficient for a simple, read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the full purpose. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema exists, the description is complete. It explains exactly what the tool does without needing to detail return values or side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and 100% schema coverage (empty schema). Baseline 4 is appropriate as the description adds no parameter information beyond the schema, which is already complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool lists the 5 major geographic regions of Brazil, naming them (Norte, Nordeste, Sudeste, Sul, CO). This clearly differentiates it from sibling tools that list states, municipalities, or aggregated data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. However, for a parameterless tool that simply lists all regions, usage is implied and straightforward.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obter_estadoA

Obtém os detalhes de um estado (UF) brasileiro.

ParametersJSON Schema

Name	Required	Description	Default
`uf`	Yes	Sigla (ex.: "SP") ou ID IBGE (ex.: "35") do estado.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It states the action is retrieving details, implying a read operation, but does not disclose the response format, potential errors, or any side effects. For a simple lookup tool, this is minimally acceptable but could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose. It is front-loaded with the key action and resource, containing no unnecessary words or information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists (as per context signals), the description does not explain what 'detalhes' are returned. This omission leaves the agent uncertain about the output structure. However, for a simple tool, it is partially complete. More detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, clearly defining the 'uf' parameter as accepting a state abbreviation or IBGE ID. The description does not add extra semantic meaning beyond the schema, but the schema itself is sufficient. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Obtém os detalhes') and the resource ('um estado (UF) brasileiro'). It distinguishes from sibling tools like 'listar_estados' (which lists all states) and 'obter_municipio' (which gets a municipality), though it does not explicitly mention these alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus others. The description implies its use for getting details of a single state, but lacks information about prerequisites or when not to use it. The parameter description is clear but does not provide usage context beyond that.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`agregado_id`	Yes	ID numérico do agregado (ex.: 6579 = "População residente estimada").

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but the description makes it clear the tool is read-only and returns metadata. It could mention response size or limits, but the presence of an output schema reduces the need. Solid for a straightforward retrieval.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with the main purpose, then immediate usage guidance. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a simple metadata tool. Covers what it does and how to use the result. With an output schema, no further details needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter with 100% schema coverage. The description adds an example value (6579) which helps contextualize the parameter beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves metadata of an aggregate from SIDRA, specifying exactly what kind (variables, periods, territorial levels). It distinguishes from sibling tools that list or query data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use the result to choose parameters for 'consultar_dados_agregado', providing clear usage context. No explicit when-not, but the guidance is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obter_municipioA

Obtém os detalhes completos de um município pelo código IBGE.

ParametersJSON Schema

Name	Required	Description	Default
`codigo`	Yes	Código IBGE do município com 7 dígitos (ex.: "3550308" = São Paulo/SP).

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It states it 'gets' details, implying read-only, but does not mention authentication, error handling, or other behaviors. For a straightforward ID lookup, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence directly states the tool's purpose without any unnecessary words. Perfectly front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present (as per context signals), the description does not need to explain return values. The tool has one parameter, low complexity, and the description completely covers its role given the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including an example and format. The description adds no new semantic value beyond what the schema already provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves complete details of a municipality by its IBGE code. Verb 'obtém' and resource 'detalhes completos de um município' are specific, and the method is precise. This distinguishes it from siblings like listar_municipios or buscar_municipios_por_nome.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use: when a municipality's IBGE code is known and full details are needed. Without explicit exclusions, the context from sibling tools (e.g., buscar_municipios_por_nome for name-based search) offers indirect guidance, but no direct 'when not' is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`codigo_municipio`	Yes	Código IBGE do município com 7 dígitos (ex.: "3550308" = São Paulo/SP).

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions the source and that it gets the latest estimate, but lacks details on behavioral traits like whether it requires authentication, is read-only, or any limitations. Minimal transparency beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the purpose, and wastes no words. It is efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter tool with an output schema, the description adequately covers purpose and source. Could mention output briefly, but it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter (codigo_municipio) with full schema description coverage (100%). The tool description does not add additional semantic info beyond that already in the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'obtém' and the resource 'população residente estimada mais recente de um município', making it unambiguous. It distinguishes from sibling tools like 'obter_projecao_populacao' by focusing on current estimates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes the data source (SIDRA aggregate 6579) but does not explicitly state when to use this tool versus alternatives like 'obter_projecao_populacao'. Usage context is implied, but no direct guidance or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obter_projecao_populacaoB

Obtém a projeção populacional do IBGE para o Brasil ou uma unidade federativa.

ParametersJSON Schema

Name	Required	Description	Default
`localidade`	No	"BR" para o Brasil, ou código IBGE de 2 dígitos de uma UF (ex.: "35").	BR

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears the full burden of behavioral disclosure, but it only states the operation is a read without details on data freshness, rate limits, or potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no fluff, efficiently conveying the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one well-described parameter and an existing output schema, the description is adequate but does not mention the projection time range or structure of results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the parameter description is clear (Brazil vs. state codes). The tool description adds no additional parameter context beyond what the schema provides, so a baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves IBGE population projections for Brazil or a state, which matches the tool name. However, it lacks specificity about the time horizon of projections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'obter_populacao_municipio'. The description does not mention any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

11 tool updatesv0.1.0Jun 10, 2026
- First observedbuscar_municipios_por_nome
- First observedconsultar_dados_agregado
- First observedlistar_agregados
- First observedlistar_estados
- First observedlistar_municipios
- First observedlistar_regioes
- First observedobter_estado
- First observedobter_metadados_agregado
- First observedobter_municipio
- First observedobter_populacao_municipio
- First observedobter_projecao_populacao

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-06-10 19:20 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.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

IBGE Brasil MCP A
io.github.SidneyBissoli
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
Government Data Location Services Open Data
23110
Inegi A
io.github.pipeworx-io
INEGI MCP — Mexico's national statistics office (INEGI) Indicators API.
Government Data Open Data
332
Dados Abertos Senado BR MCP A
io.github.SidneyBissoli
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
Government Data Open Data
6926
Eurostat A
io.github.pipeworx-io
Eurostat MCP — wraps Eurostat Statistical Data API (no auth required)
Open Data Government Data Research & Data
342

Related MCP Servers

IBGE Brasil MCP
Government Data Open Data Research & Data
SidneyBissoli
A
license
A
quality
A
maintenance
This server provides access to IBGE's public APIs, enabling AI assistants to query geographic, demographic, and statistical data from Brazil.
Updated a day ago (2026-09-14 22:11 UTC)
23
274 npm
10
MIT
Banco Central do Brasil (BCB)
Finance Government Data Open Data
SidneyBissoli
A
license
A
quality
A
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
Updated a day ago (2026-09-14 21:53 UTC)
15
220 npm
8
MIT
mcp-brasil
Government Data Open Data Search
Mcp-Brasil
A
license
A
quality
C
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.
Updated a month ago (2026-08-19 00:43 UTC)
7
1,759
MIT
mcp-ibge-br
Government Data Open Data
pipeworx-io
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.
Updated 3 days ago (2026-09-13 06:45 UTC)
5 npm
MIT