Skip to main content
Glama
Sign In
usp-mcp

usp-mcp

by iDavi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

usp-mcp

MCP (Model Context Protocol) server para os sistemas estudantis da Universidade de São Paulo — Moodle (e-Disciplinas), JupiterWeb, notas, faltas, grade horária e tarefas — usando o Heidy backend como camada de acesso segura.

Com ele, um assistente (Claude Desktop, Claude Code, ou qualquer cliente MCP) consegue responder coisas como "quais atividades tenho no Moodle essa semana?", "como está minha média em ACH2034?" ou "monta minha grade de horários".

Como funciona

cliente MCP  ──stdio/HTTP──▶  usp-mcp (Python/FastAPI)  ──HTTPS──▶  Heidy backend  ──▶  Moodle / JupiterWeb

  • A senha nunca viaja em texto claro. No login, o servidor busca a chave pública atual do backend (GET /auth/login-key) e sela a Senha Única num envelope HPKE-Base(X25519, HKDF-SHA256, AES-256-GCM). Só o backend consegue abri-lo, e a senha não é retida em lugar nenhum deste processo depois do login.

  • A sessão vive só em memória. O login devolve um bearer token e um credential blob (ciphertext opaco que só o backend abre); ambos ficam apenas na memória do processo e são descartados no logout.

Related MCP server: Horizon

Instalação

pip install .          # ou: pip install -e .[dev] para desenvolver

Uso

stdio (Claude Desktop / Claude Code)

usp-mcp

Configuração para Claude Desktop/Code (mcpServers):

{
  "mcpServers": {
    "usp": {
      "command": "usp-mcp"
    }
  }
}

HTTP (FastAPI + Streamable HTTP)

usp-mcp --http --port 8000
# ou diretamente:
uvicorn usp_mcp.app:app --host 0.0.0.0 --port 8000

  • Endpoint MCP: http://localhost:8000/mcp

  • Health check (deste serviço e do backend): http://localhost:8000/health

Variáveis de ambiente

Variável

Efeito

HEIDY_BASE_URL

Backend alternativo (padrão: https://heidy-backend.fly.dev)

HEIDY_USERNAME

Número USP para login automático na primeira ferramenta

HEIDY_PASSWORD

Senha Única para login automático

HEIDY_DOWNLOAD_DIR

Pasta padrão para moodle_download_file (padrão: ./downloads)

Sem HEIDY_USERNAME/HEIDY_PASSWORD, chame a ferramenta usp_login primeiro.

Ferramentas

Ferramenta

O que faz

usp_login / usp_logout

Abre/encerra a sessão com número USP + Senha Única

get_profile

Perfil do estudante

moodle_courses

Disciplinas no e-Disciplinas

moodle_course

Conteúdo de uma disciplina (atividades, materiais)

moodle_activity

Abre uma atividade pelo URL (conteúdo, links, metadados de arquivo)

moodle_download_file

Baixa um arquivo do Moodle (PDF, slides, ...) para o disco (até 10 MB)

usp_sync / usp_sync_status / usp_sync_history

Sincroniza grade, notas, faltas e Moodle do JupiterWeb

list_semesters

Semestres do estudante

get_schedule

Grade horária semanal de um semestre

list_enrollments

Matrículas (turmas), com horários e professor

list_grades / grade_summary

Notas e média ponderada/status de aprovação por turma

list_absences / absence_summary

Faltas e situação frente ao limite

list_tasks / create_task / update_task_status

Tarefas do planner (provas, entregas, leituras)

Desenvolvimento

pip install -e .[dev]
pytest

Os testes cobrem o esquema de criptografia do envelope (compatível com o vault do backend), o cliente HTTP (com backend simulado) e a superfície de ferramentas MCP.

Available Tools

20 tools
absence_summaryC

Absences used vs. the enrollment's limit, with a risk status.

Inputs: enrollment_id (required). Returns: object

create_taskC

Create a task in the student's planner. due_at is an ISO 8601 datetime.

Inputs: title (required), kind, notes, due_at, +3 more. Returns: object

get_profileA

The logged-in student's profile (name, USP number, email, course).

Inputs: no named parameters. Returns: object

get_scheduleC

The weekly class schedule for a semester: day -> time slots with locations.

Inputs: semester_id (required). Returns: object

grade_summaryC

Weighted average, graded/remaining weight and passing status for an enrollment.

Inputs: enrollment_id (required). Returns: object

list_absencesC

Absences recorded for one enrollment.

Inputs: enrollment_id (required). Returns: result

list_enrollmentsC

The student's enrollments (classes), with meetings, professor and credits.

Inputs: source, semester_id. Returns: object

list_gradesC

Grades recorded for one enrollment (label, score, max score, weight).

Inputs: enrollment_id (required). Returns: result

list_semestersA

The student's semesters (label, start/end dates, which one is active).

Inputs: no named parameters. Returns: object

list_tasksB

The student's tasks (assignments, exams, ...), filterable and sortable.

due_before/due_after are ISO 8601 datetimes.

Inputs: kind, sort, status, due_after, +3 more. Returns: object

moodle_activityA

Open a Moodle activity by URL: page content, links and attached file, if any.

For file activities (PDFs, slides, ...) this returns the file's name, type and size — use moodle_download_file to save the bytes to disk.

Inputs: url (required). Returns: object

moodle_courseB

A Moodle course's contents: its sections and activities (id, title, kind, url).

Inputs: course_id (required). Returns: object

moodle_coursesB

List the student's current Moodle (e-Disciplinas) courses.

Inputs: no named parameters. Returns: result

moodle_download_fileA

Download a Moodle file activity (PDF, slides, ...) to local disk.

url is the activity URL from moodle_course (kind "Arquivo"/"Resource"). Saves into directory (default: $HEIDY_DOWNLOAD_DIR or ./downloads) and returns the saved path, name, MIME type and size. Files up to 10 MB.

Inputs: url (required), directory. Returns: object

update_task_statusB

Move a task between todo, doing and done.

Inputs: status (required), task_id (required). Returns: object

usp_loginA

Log in to USP with the USP number and Senha Única.

The password is encrypted to the backend's login key before leaving this process and is never stored. Returns the student's profile.

Inputs: password (required), usp_username (required). Returns: object

usp_logoutA

Log out, revoking the current session token.

Inputs: no named parameters. Returns: object

usp_syncA

Start a background sync pulling data from USP systems into the planner.

Sources default to all of schedule, grades, absences and moodle. Returns the sync run; poll usp_sync_status with its id until it succeeds or fails.

Inputs: sources, semester_id. Returns: object

usp_sync_historyC

Past sync runs, optionally filtered by status.

Inputs: status. Returns: object

usp_sync_statusC

A sync run's status, per-source counts and error, if any.

Inputs: run_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.3/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a distinctly clear purpose. For example, absence_summary provides a risk overview while list_absences returns individual records; moodle_activity, moodle_course, and moodle_download_file each cover different aspects of Moodle interaction. No overlapping functionality that would confuse an agent.

    Naming Consistency5/5

    All tool names use a consistent lowercase_with_underscores pattern, predominantly verb_noun (list_*, create_*, get_*, update_*, moodle_*, usp_*). Even summary tools like absence_summary and grade_summary follow a predictable noun_noun pattern without deviating from the overall style.

    Tool Count4/5

    With 20 tools covering student profile, enrollments, grades, absences, schedule, tasks, Moodle, and sync/login/logout, the count is slightly high but justifiable given the breadth of integrated USP systems. It remains manageable and each tool is focused.

    Completeness4/5

    The tool surface is largely complete for the domain: CRUD for tasks (create, list, status update, but missing delete and full update), read-only access to grades/absences/schedule, comprehensive Moodle interaction, and sync management. Minor gaps exist (e.g., no task deletion, no per-semester enrollment filtering), but agents can work around them.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcpUPB

      olartgabo
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that turns UPB Virtual (Moodle) into a structured knowledge source, enabling AI assistants to query courses, assignments, deadlines, announcements, and sync materials via REST API.
      MIT

    • Horizon

      hamzakammar
      A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that connects AI assistants to university D2L Brightspace and Piazza, enabling query of courses, grades, assignments, deadlines, files, and Piazza posts.
      7
      MIT

    • PUCP-MCP

      Hellowda253
      A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server kit that connects AI assistants to PUCP's Paideia and Campus Virtual portals, allowing students to query courses, materials, grades, schedules, and enrollment information locally with their own credentials.
      4
      MIT