Natal IBGE MCP Server

O Natal IBGE MCP Server é um servidor implementado seguindo o padrão Model Context Protocol (MCP) da Anthropic. Ele disponibiliza a modelos de Inteligência Artificial (como Claude, GPT-4o, Gemini, etc.) acesso estruturado e direto a dados oficiais do Censo Demográfico 2022 e do PIB para a cidade de Natal (RN) — código IBGE 2408102.

O servidor combina consultas dinâmicas às APIs públicas agregadas do IBGE/SIDRA com dados extremamente granulares a nível de bairros fornecidos por planilhas locais preprocessadas, tornando-se uma ferramenta indispensável para análises econômicas, demográficas e habitacionais da capital potiguar.

---

Requisitos

• Node.js (Versão recomendada: >= 18)
• NPM (incluso com o Node)

---

Instalação e Configuração

1. Clonar e Instalar o Servidor

Clone este repositório no seu computador e instale as dependências:

git clone <url-do-repositorio>
cd mcp-ibge-natal
npm install
npm run build

2. Adicionar ao Claude Desktop

Abra o arquivo de configuração do seu Claude Desktop (claude_desktop_config.json). No macOS, ele fica em: ~/Library/Application Support/Claude/claude_desktop_config.json

Adicione a seguinte configuração no objeto "mcpServers":

{
  "mcpServers": {
    "mcp-ibge-natal": {
      "command": "node",
      "args": ["/Users/fabiofariasfigueiroa/Desktop/mcp-ibge-natal/build/index.js"]
    }
  }
}

3. Adicionar ao Cursor IDE

1. Abra o Cursor e vá nas configurações (Settings -> Features -> MCP).
2. Clique em + Add New MCP Server.
3. Configure os seguintes valores:
   • Name: mcp-ibge-natal
   • Type: stdio
   • Command: node "/Users/fabiofariasfigueiroa/Desktop/mcp-ibge-natal/build/index.js"
4. Clique em Save.

---

Atualizar dados por bairro

Os arquivos CSV em data/ são gerados a partir de fontes públicas do IBGE, utilizando os scripts de extração disponíveis no projeto:

python3 scripts/extract_natal_bairros.py   # população, domicílios e esgotamento por bairro
python3 scripts/extract_natal_renda.py     # renda do responsável pelo domicílio por bairro

Requer Python 3 instalado na máquina.

Como os dados são provenientes do Censo 2022 (estáticos), não é necessário rodar os scripts novamente a menos que as fontes sejam atualizadas. Execute-os apenas quando houver uma nova versão dos dados de origem.

Sobre a renda por bairro: o dado granular é o rendimento do responsável pelo domicílio (chefe), do release IBGE "Agregados por Setores Censitários — Rendimento do Responsável". É um universo distinto da tool municipal get_average_income (que cobre todas as pessoas de 14+ anos ocupadas), portanto os números por bairro não são diretamente comparáveis com o municipal.

---

Ferramentas Disponíveis (MCP Tools)

Nome da Ferramenta	Descrição	Parâmetros
get_total_population	População total residente de Natal (Censo 2022).	Nenhum
get_population_by_age_group	Pirâmide/faixa etária com proporção (%) por faixa.	Nenhum
get_population_history	Série histórica das estimativas populacionais.	Nenhum
get_gdp_pib	PIB a preços correntes de Natal (2022).	Nenhum
compare_gdp_neighbors	Comparativo de PIB: Natal vs. Parnamirim, São Gonçalo do Amarante e Mossoró.	Nenhum
get_average_income	Renda nominal média e mediana mensal dos trabalhadores (Censo 2022).	Nenhum
get_households_count	Total de domicílios particulares permanentes ocupados.	Nenhum
get_density_area	Área territorial (km²) e densidade demográfica (hab/km²).	Nenhum
get_city_sanitation	Panorama do esgotamento sanitário do município.	Nenhum
get_literacy_rate	Taxa de alfabetização das pessoas de 15+ anos (Censo 2022).	Nenhum
list_neighborhoods	Lista os 36 bairros com população, área, densidade, moradores/dom. e renda média do responsável.	Nenhum
get_neighborhood_demographics	Demografia e ocupação de domicílios de um bairro.	query (nome ou código)
get_neighborhood_sanitation	Detalhamento do esgotamento e % de adequação por bairro.	query (nome ou código)
get_neighborhood_income	Renda média e mediana mensal do responsável pelo domicílio em um bairro, com ranking (Censo 2022).	query (nome ou código)
rank_neighborhoods_by_income	Ranqueia os bairros pela renda média do responsável (maiores ou menores).	order (top/bottom), limit
compare_neighborhoods	Tabelas comparativas lado a lado entre bairros (demografia, saneamento e renda).	bairros (array, mín. 2)

---

Exemplos de Perguntas

Depois de configurar o servidor MCP, você pode conversar com o assistente e fazer perguntas como:

• "Qual o PIB de Natal comparado a Parnamirim, São Gonçalo do Amarante e Mossoró?"
• "Como é a pirâmide etária de Natal?"
• "Qual a taxa de alfabetização de Natal?"
• "Quais os 3 bairros mais populosos de Natal e suas densidades?"
• "Compare o saneamento (esgotamento adequado) entre Pajuçara e Lagoa Azul."
• "Qual a média de moradores por domicílio no bairro Petrópolis?"
• "Qual a renda do responsável pelo domicílio no bairro Tirol?"
• "Quais os 5 bairros de Natal com menor renda do responsável?"
• "Compare renda, saneamento e densidade entre Tirol e Guarapés."

---

Estrutura de Pastas

├── data/
│   ├── bairros_natal.csv                  # Dados demográficos locais por bairro
│   ├── esgotamento_por_bairro_natal.csv   # Dados de esgoto locais por bairro
│   └── renda_por_bairro_natal.csv         # Renda do responsável pelo domicílio por bairro
├── scripts/
│   ├── extract_natal_bairros.py           # Extração de população/domicílios/esgoto por bairro
│   ├── extract_natal_renda.py             # Extração da renda do responsável por bairro
│   └── verify.js                          # Script de verificação da integração MCP
├── src/
│   └── index.ts                           # Implementação principal do servidor MCP (TypeScript)
├── build/
│   └── index.js                           # Servidor compilado (JavaScript executável)
├── package.json                           # Dependências e scripts do projeto
├── tsconfig.json                          # Configuração do compilador TypeScript
└── README.md                              # Documentação de referência

---

Licença

Este projeto está licenciado sob a licença MIT. Desenvolvido para facilitar o acesso à informação pública e fomentar a cultura de Letramento de Dados.