# IDEB MCP

Conecte o Claude ao banco de dados do **IDEB** (Índice de Desenvolvimento da Educação Básica) e consulte o desempenho educacional de qualquer município brasileiro diretamente na conversa.

Cobre os 10 ciclos de avaliação (2005 a 2023) para cerca de 5.570 municípios, nas redes Estadual, Municipal e Pública, com IDEB observado, metas projetadas, notas de Matemática e Português e indicador de fluxo escolar.

Dados públicos do INEP/MEC.

---

## O que você pode perguntar

<!-- INSERIR PRINT: conversa mostrando ranking de municípios de SP -->

<!-- INSERIR PRINT: conversa mostrando série histórica de um município -->

<!-- INSERIR PRINT: conversa comparando dois municípios -->

---

## Etapas disponíveis

| Etapa | Descrição |
|-------|-----------|
| Anos Iniciais | Ensino Fundamental — 1º ao 5º ano |
| Anos Finais | Ensino Fundamental — 6º ao 9º ano |
| Ensino Médio | Ensino Médio |

---

## Instalação passo a passo

### 1. Instale o Python

Acesse https://www.python.org/downloads e baixe a versão mais recente.

> **Windows:** durante a instalação, marque a opção **"Add Python to PATH"** antes de clicar em Install.

Para verificar se a instalação funcionou, abra o terminal e digite:
```
python --version
```

### 2. Instale o Git

Acesse https://git-scm.com/downloads e instale o Git para o seu sistema.

Para verificar:
```
git --version
```

### 3. Instale o Git LFS

O banco de dados do IDEB tem ~75MB e é armazenado via Git LFS (Large File Storage). Acesse https://git-lfs.com e instale.

Para verificar:
```
git lfs version
```

### 4. Clone o repositório

Abra o terminal e rode:

```bash
git lfs install
git clone https://github.com/rafaelcamelo/ideb-mcp.git
cd ideb-mcp
```

### 5. Instale o pacote

```bash
pip install -e .
```

---

## Configuração no Claude Desktop

> Não tem o Claude Desktop? Baixe em https://claude.ai/download

**1.** Abra o arquivo de configuração do Claude Desktop:

- **Windows:** pressione `Win + R`, digite `%APPDATA%\Claude` e abra o arquivo `claude_desktop_config.json`
- **macOS:** abra o Finder, pressione `Cmd + Shift + G`, cole `~/Library/Application Support/Claude` e abra o arquivo `claude_desktop_config.json`

Se o arquivo não existir, crie-o.

**2.** Adicione o servidor IDEB ao JSON. Se o arquivo estiver vazio, cole isto:

```json
{
  "mcpServers": {
    "ideb": {
      "command": "python",
      "args": ["-m", "ideb_mcp"]
    }
  }
}
```

Se o arquivo já tiver conteúdo, adicione apenas o bloco `"ideb"` dentro de `"mcpServers"`:

```json
{
  "mcpServers": {
    "ideb": {
      "command": "python",
      "args": ["-m", "ideb_mcp"]
    }
  }
}
```

> **Windows:** se o Claude não encontrar o Python, substitua `"python"` pelo caminho completo. Para descobrir o caminho, abra o terminal e rode `where.exe python`. O resultado será algo como `C:\Users\SEU_USUARIO\AppData\Local\Programs\Python\Python312\python.exe` — use esse valor no lugar de `"python"`.

**3.** Salve o arquivo e **reinicie o Claude Desktop completamente** (feche pelo ícone na bandeja do sistema, não só a janela).

**4.** Abra uma nova conversa e pergunte algo como:

> "Qual o IDEB de Campinas em 2023?"

---

## Outros clientes compatíveis

O protocolo MCP é suportado por outros clientes além do Claude Desktop. A configuração varia — consulte a documentação de cada um:

- **[Cursor](https://cursor.com)** — editor de código com IA
- **[Zed](https://zed.dev)** — editor de código com IA
- **[Continue](https://continue.dev)** — extensão para VS Code e JetBrains

> **ChatGPT e Gemini** não suportam o protocolo MCP nativamente.

---

## Exemplos de perguntas

**Consulta por município:**
- "Qual o IDEB de Ariquemes (RO) nos anos iniciais?"
- "Como foi a evolução do IDEB de Campinas de 2005 a 2023?"
- "Qual a nota de Matemática de São Paulo nos anos finais em 2023?"

**Rankings:**
- "Quais os 10 municípios com melhor IDEB no Ensino Médio em MG?"
- "Qual município de SC teve o pior IDEB nos anos iniciais em 2023?"

**Comparações:**
- "Compare o IDEB de Curitiba e Londrina nos anos finais"
- "Qual cresceu mais entre 2005 e 2023: Recife ou Fortaleza?"

**Visão geral:**
- "Qual a média do IDEB nos anos iniciais no Brasil em 2023?"
- "Qual estado tem a maior média de IDEB no Ensino Médio?"

---

## Procedência dos dados

Extraídos das planilhas públicas de divulgação de resultados do IDEB por município, disponibilizadas pelo INEP/MEC em https://www.gov.br/inep/pt-br/areas-de-atuacao/avaliacao-e-exames-educacionais/ideb/resultados.

---

## Licença

Código sob licença MIT. Dados do IDEB são públicos (INEP/MEC).