MCP 服务器

ab-ibge-mcp-server

Enables AI agents to access Brazilian statistical, geographic, and economic data in real-time via IBGE public APIs.

README

🇧🇷 IBGE MCP Server

Servidor MCP (Model Context Protocol) para as APIs públicas do IBGE, permitindo que agentes de IA como Claude acessem dados estatísticos, geográficos e econômicos do Brasil em tempo real.

✨ Versão 2.2.0 — Agora com suporte HTTP/SSE, cache inteligente, API de Nomes e suporte multi-variável!

Sponsored by Aeon Bridge Co. 🌉 Building the future of AI-powered data integration. Contact: contact@aeonbridge.com

✨ Ferramentas Disponíveis (27+ tools)

📍 Localidades

Tool	Descrição
`ibge_listar_regioes`	Lista as 5 regiões geográficas com seus estados
`ibge_listar_estados`	Lista todos os 27 estados com sigla, ID e região
`ibge_listar_municipios`	Lista municípios de um estado (busca flexível sem acentos)
`ibge_buscar_municipio`	Busca município por nome em todo Brasil (suporta "Sao Paulo")

📊 SIDRA (Sistema de Recuperação Automática)

Tool	Descrição
`ibge_sidra_pesquisar_tabelas`	Pesquisa tabelas por assunto (ex: "PIB", "agricultura")
`ibge_sidra_metadados_tabela`	Metadados de uma tabela (variáveis, períodos, localidades)
`ibge_sidra_consultar_tabela`	Consulta dados com múltiplas variáveis simultaneamente
`ibge_periodos_tabela`	Lista períodos disponíveis de uma tabela
`ibge_ipca`	Inflação IPCA mensal com série histórica
`ibge_pib_municipios`	PIB dos municípios (tabela 5938)
`ibge_pib_estados`	NOVO — PIB dos estados com ranking nacional

📈 Indicadores Econômicos

Tool	Descrição
`ibge_indicador_economico`	IPCA, IPCA acumulado, desemprego, rendimento, INPC
`ibge_listar_indicadores`	Lista todos os indicadores disponíveis

👥 Censo e População

Tool	Descrição
`ibge_populacao_municipio`	População de um município pelo Censo 2022
`ibge_populacao_estados`	Ranking de população de todos os estados
`ibge_densidade_demografica`	Densidade demográfica (hab/km²) por estado
`ibge_populacao_censo2022`	Dados populacionais do Censo com filtros avançados
`ibge_estimativas_populacionais`	NOVO — Estimativas anuais (2001-2024+) para municípios e estados

🏷️ API de Nomes (Censo)

Tool	Descrição
`ibge_nomes_frequencia`	NOVO — Frequência histórica de um nome (ex: "João") por década
`ibge_nomes_ranking`	NOVO — Top 20 nomes mais populares do Brasil ou por UF

🗺️ Malha e Notícias

Tool	Descrição
`ibge_malha_geografica`	URL da malha geográfica (GeoJSON/SVG)
`ibge_noticias`	Notícias e releases do IBGE

🚀 Instalação

Instalação via npm (Recomendado)

# Instale globalmente via npm
npm install -g ab-ibge-mcp-server

Instalação manual (Desenvolvimento)

# 1. Clone ou copie o projeto
cd ibge-mcp-server

# 2. Instale as dependências
npm install

# 3. Compile o TypeScript
npm run build

# 4. Teste o servidor
node dist/index.js

🌐 Modos de Transporte

O servidor suporta dois modos de transporte:

Modo	Uso	Comando
stdio (padrão)	Uso local com Claude Desktop, CLI	`npm start`
http	Deploy cloud, múltiplos clientes	`npm run start:http`

Modo HTTP (Novo!)

Para usar o servidor via HTTP/SSE em vez de stdio:

# Desenvolvimento
npm run dev:http

# Produção
npm run start:http

# Customizar porta
MCP_TRANSPORT=http PORT=8080 npm start

Endpoints disponíveis:

GET /health — Health check
POST /sse — Conexão MCP via Server-Sent Events

📖 Documentação completa: HTTP_MODE.md

⚙️ Configuração no Claude Desktop

Se instalou via npm global

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ibge": {
      "command": "ab-ibge-mcp-server"
    }
  }
}

Se instalou manualmente

{
  "mcpServers": {
    "ibge": {
      "command": "node",
      "args": ["/caminho/para/ibge-mcp-server/dist/index.js"]
    }
  }
}

Reinicie o Claude Desktop. O ícone 🔌 aparecerá indicando que o servidor está conectado.

💡 Exemplos de Uso com Agentes IA

Usuário: "Qual o estado mais populoso do Brasil?"
Agente: ibge_populacao_estados() → São Paulo com 44,4 milhões de habitantes (21,7% do total)

Usuário: "Quantas pessoas se chamam Maria no Brasil?"
Agente: ibge_nomes_frequencia(nome="Maria") → 11,7 milhões de pessoas registradas

Usuário: "Quais os nomes masculinos mais populares na década de 1990?"
Agente: ibge_nomes_ranking(sexo="M", decada=1990) → Top 20 com frequência

Usuário: "Qual o PIB de São Paulo em 2021?"
Agente: ibge_pib_estados(ano=2021, uf_id=35) → R$ 2,7 trilhões (31% do PIB nacional)

Usuário: "População estimada do Brasil em 2024"
Agente: ibge_estimativas_populacionais(ano=2024, localidade="BR") → 212,6 milhões

Usuário: "Compare inflação de 2023 e 2024 mês a mês"
Agente: ibge_indicador_economico(indicador="IPCA", periodos="202301-202412")

Usuário: "Liste todas as cidades de SC com 'Floriano' (sem acento)"
Agente: ibge_listar_municipios(uf="SC", busca="Floriano") → Florianópolis encontrada!

Usuário: "Busque 'Sao Paulo' (sem acento)"
Agente: ibge_buscar_municipio(nome="Sao Paulo") → São Paulo-SP encontrado (normalização automática)

Usuário: "Qual a densidade demográfica do DF vs SP?"
Agente: ibge_densidade_demografica() → DF: 529.2 hab/km², SP: 177.3 hab/km²

Usuário: "Consulte IPCA e INPC simultaneamente"
Agente: ibge_sidra_consultar_tabela(tabela="1419", variaveis="63|44") → Múltiplas variáveis em uma chamada

🔧 Tecnologias e Performance

TypeScript com tipagem estrita
MCP SDK (@modelcontextprotocol/sdk)
APIs do IBGE — 100% públicas, sem autenticação necessária
Zod para validação de inputs
Cache in-memory com TTL inteligente (até 7 dias para dados imutáveis)
Retry automático com exponential backoff para maior confiabilidade
Busca sem acentos — aceita "Sao Paulo", "Florianopolis", etc.

📚 APIs do IBGE Utilizadas

API	Versão	Endpoint Base
Localidades	v1	`servicodados.ibge.gov.br/api/v1/localidades`
SIDRA	v3	`servicodados.ibge.gov.br/api/v3/agregados`
Malha Geográfica	v2	`servicodados.ibge.gov.br/api/v2/malhas`
Notícias	v3	`servicodados.ibge.gov.br/api/v3/noticias`

🤝 Sponsorship

This project is proudly sponsored by Aeon Bridge Co. 🌉

Aeon Bridge Co. is a technology company focused on building innovative solutions for AI-powered data integration and intelligent systems. We bridge the gap between complex data sources and modern AI agents, making information accessible and actionable.

Learn more: https://aeonbridge.com Contact: contact@aeonbridge.com