🇧🇷 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

---

📄 License

MIT License - See LICENSE file for details.

🙏 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

---

Made with ❤️ by the Aeon Bridge team