Poliedro MCP Server

Servidor MCP não oficial para consultar informações do portal Poliedro/P+. Este projeto não é afiliado, endossado ou mantido pelo Poliedro Sistema de Ensino.

Funcionalidades:

• Boletim / notas
• Mensagens / notificações
• Calendário escolar: próximos eventos, semana, mês e ano
• Funciona com Claude Desktop (vide docs/)

Requisitos

• Python 3.11 ou superior
• macOS (o setup salva a senha no Keychain; em Linux use POLIEDRO_TOKEN)
• Conta ativa no P+ (responsável ou aluno)

Primeira instalação

Execute os comandos na raiz do repositório (poliedro-mcp/), não dentro de config/:

cd poliedro-mcp

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
pip install -e .

cp config/config.example.json config/config.json

O config.json inicial pode manter só a base_url correta; os demais campos (auth, student, calendar) são preenchidos no passo de login abaixo.

Login e configuração automática

python -m poliedro_mcp.setup_login

O script:

1. Pede o usuário (se auth.username estiver vazio ou for placeholder no config)
2. Pede a senha (mesma do login em https://pmais.p4ed.com/)
3. Valida o acesso na API do Poliedro
4. Salva a senha no Keychain do macOS (serviço poliedro-pmais)
5. Atualiza config/config.json com username, dados do aluno e calendário

Confira no final a saída com school_id, email_p4ed, enrollment_id, etc.

Validar instalação

python -m poliedro_mcp.cli health
python -m poliedro_mcp.cli grades
python -m poliedro_mcp.cli messages
python -m poliedro_mcp.cli calendar next

Segurança

Não coloque senha nem token no config.json.

Autenticação suportada:

1. Keychain (recomendado no Mac) — configure com python -m poliedro_mcp.setup_login
2. Token manual — variável de ambiente POLIEDRO_TOKEN (útil em CI/Linux)

Para produção remota, substitua o Keychain por Secret Manager, KMS ou cofre equivalente.

Problemas comuns

HTTP 401 / Invalid user credentials

A API rejeitou usuário ou senha. Confira:

• Usuário igual ao do P+ (ex.: nome.sobrenome, sem @p4ed.com)
• Senha digitada corretamente (o terminal não mostra caracteres ao digitar)
• Conta funcionando no site https://pmais.p4ed.com/

Rode o setup de novo após corrigir:

cd /caminho/para/poliedro-mcp
source .venv/bin/activate
python -m poliedro_mcp.setup_login

ModuleNotFoundError: poliedro_mcp

Ative o venv e instale o pacote na raiz do repo:

source .venv/bin/activate
pip install -e .

Arquivo de configuração não encontrado

cp config/config.example.json config/config.json

Config em outro caminho

export POLIEDRO_CONFIG=/caminho/absoluto/config.json

Rodar como MCP stdio

python -m poliedro_mcp.server

Configuração no Claude Desktop

Substitua /CAMINHO/ABSOLUTO/poliedro-mcp pelo caminho real do projeto:

{
  "mcpServers": {
    "poliedro": {
      "command": "/CAMINHO/ABSOLUTO/poliedro-mcp/.venv/bin/python",
      "args": ["-m", "poliedro_mcp.server"],
      "cwd": "/CAMINHO/ABSOLUTO/poliedro-mcp"
    }
  }
}

Ferramentas MCP expostas

• poliedro_health_check
• get_grades
• get_unread_messages
• get_messages
• get_next_events
• get_week_events
• get_month_events
• get_year_events

Observação sobre remoto

Este projeto está pronto para virar um MCP remoto, mas o mais seguro é validar localmente antes.

Para remoto, recomenda-se:

• HTTPS obrigatório
• Autenticação do MCP
• Tokens Poliedro criptografados por usuário
• Banco de dados para mapa usuário → credenciais
• Secrets Manager/KMS

Licença

Este projeto está licenciado sob a MIT License.

O código deste repositório é open source; o uso da API e do portal P+ continua sujeito aos termos de uso do Poliedro. Cada usuário é responsável por suas próprias credenciais e pelo cumprimento desses termos.