Skip to main content
Glama
Moodle MCP (Aula USM)

Moodle MCP (Aula USM)

by muitomou

Moodle MCP (Aula USM)

tests python licencia

Servidor MCP (Model Context Protocol) que le da a Claude acceso a tu Moodle como estudiante: ramos, próximas entregas, enunciados de tareas, materiales, notas, avisos y foros. Así puedes preguntarle cosas como:

«¿Qué tengo que entregar esta semana?» «Léeme el enunciado de la Tarea 2 de Bioinformática y dime qué archivos necesito.» «Baja las guías de la unidad 3 de pds a mi carpeta del ramo.» «¿Cómo voy en Inteligencia Artificial?»

Está pensado para Aula USM (https://aula.usm.cl), pero funciona con cualquier Moodle que tenga habilitado el servicio de la app móvil oficial (moodle_mobile_app).

Proyecto personal y no oficial: no está afiliado a la USM ni a Moodle HQ.

Qué puede hacer

Herramienta

Para qué

listar_ramos

Ramos vigentes (o todos), con sigla, paralelos y carpeta local

proximas_entregas

Tareas y actividades con fecha límite, incluidas las atrasadas

ver_tarea

Enunciado, adjuntos, fechas, formato de entrega y estado de tu entrega

leer_material

Lee el texto de un PDF o archivo del ramo (y lo guarda en tu carpeta)

contenido_ramo

Secciones, recursos y archivos de un ramo

descargar_material

Baja archivos a la carpeta local del ramo

ver_notas

Nota final por ramo o el detalle de cada evaluación

avisos_y_foros / leer_discusion

Avisos y discusiones de los foros

contactos_ramo

Profesores y ayudantes (mejor esfuerzo: depende de cómo esté configurado cada ramo)

vincular_carpeta

Elige qué carpeta local corresponde a cada ramo

Respecto a Moodle todo es de solo lectura. Lo único que escribe es tu disco: las descargas y el archivo que vincula ramos con carpetas.

Related MCP server: Monash Study Kit

Cómo funciona

Claude (Code / Desktop) ──MCP (stdio)──▶ aula-mcp ──HTTPS + token──▶ API REST de Moodle
                                            │
                                            └──▶ ~/UNIVERSIDAD/<ramo>/Aula/…   (descargas)
  • Usa la API REST oficial de Moodle con el mismo permiso que la app móvil, sin scraping: las respuestas son estables y no se rompen cuando cambia el diseño del sitio.

  • Las respuestas se resumen y se compactan (sin HTML, fechas legibles, sin campos vacíos) para gastar pocos tokens: una tarea completa cuesta unos 160 tokens y un enunciado en PDF de 4 páginas, unos 3 300.

  • Los datos que cambian poco (ramos, contenidos) se guardan en caché por 10 minutos.

Instalación

Requiere Python 3.10 o superior.

git clone https://github.com/muitomou/moodle-mcp-aula-usm.git
cd moodle-mcp-aula-usm
python3 -m venv .venv
.venv/bin/pip install -e .

Obtener el token

Aula USM usa inicio de sesión con Microsoft, así que no hay usuario y contraseña que el programa pueda usar. En su lugar se usa el mismo flujo que la app móvil oficial:

.venv/bin/aula-mcp-login --dir-base ~/Escritorio/UNIVERSIDAD
  1. Se abre Aula en tu navegador. Antes de iniciar sesión, abre las herramientas de desarrollo (F12) en la pestaña Consola.

  2. Inicia sesión normalmente.

  3. Moodle intenta abrir la app y la consola muestra Failed to launch 'moodlemobile://token=…'. Copia esa URL completa.

  4. Pégala en la terminal. El programa verifica la firma, prueba el token y lo guarda en ~/.config/aula-mcp/config.env con permisos 600.

Si ya tienes un token (por ejemplo, en Preferencias → Claves de seguridad), usa aula-mcp-login --token.

Para comprobar que todo funciona:

.venv/bin/aula-mcp-check

Conectarlo a Claude

Claude Code

claude mcp add --scope user aula -- "$PWD/.venv/bin/aula-mcp"

Claude Desktop: cierra la app por completo, incluso desde la bandeja del sistema, y ejecuta:

.venv/bin/aula-mcp-desktop

Este comando agrega el servidor a claude_desktop_config.json y respalda el archivo antes. Luego abre la app. Tiene que estar cerrada porque Claude Desktop reescribe ese archivo mientras está abierta y borraría el cambio.

Desde el celular: el servidor corre en tu computador, porque ahí están el token y tus carpetas. Con Remote Control de Claude Code puedes seguir desde la app de Claude en el celular una sesión que corre en tu computador, y esa sesión tiene acceso al MCP. Un conector remoto propio (HTTP + OAuth) está en la hoja de ruta.

Configuración

Variable

Por defecto

Uso

AULA_URL

https://aula.usm.cl

URL de tu Moodle

AULA_TOKEN

—

Token (lo escribe aula-mcp-login)

AULA_DIR_BASE

—

Carpeta con una subcarpeta por ramo

AULA_CONFIG_DIR

~/.config/aula-mcp

Dónde se guardan config.env y carpetas.json

Las variables de entorno tienen prioridad sobre config.env.

Carpetas por ramo

Si AULA_DIR_BASE apunta a una carpeta como esta:

UNIVERSIDAD/
├── pds/                ← (INF331) Pruebas de Software
├── seminariosisges/    ← (INF363) Seminario de Sistemas y Gestión
├── IA/                 ← (INF295) Inteligencia Artificial
└── 2025-2/             ← semestres pasados (se busca un nivel adentro)
    └── DIU/

el MCP reconoce la carpeta de cada ramo por su nombre, su sigla (INF331) o abreviaturas del nombre: pds → Pruebas de Software, seminariosisges → Seminario de Sistemas y Gestión. Cada candidata recibe un puntaje: nombre exacto o sigla > abreviatura larga > abreviatura corta, y las palabras como «de» o «a» restan. Si una gana con claridad, la usa y la recuerda; si no, pide elegir con vincular_carpeta. Nunca crea carpetas por su cuenta. Los archivos quedan en <carpeta del ramo>/Aula/<sección>/.

Las mismas abreviaturas sirven para nombrar ramos: «¿qué tengo pendiente en pds?».

Los nombres que entrega Aula USM, como (202602)(INF331) PRUEBAS DE SOFTWARE|Paralelos:200, se limpian para quedar en sigla, nombre y paralelos.

Para que un ramo dado de baja no aparezca entre los vigentes, ocúltalo en Aula (Mis cursos → ⋯ → Quitar de la vista): listar_ramos respeta esa preferencia.

Seguridad y privacidad

  • El token da acceso a tu cuenta de Moodle como lo haría la app móvil: trátalo como una contraseña. Vive fuera del repositorio, con permisos 600, y el token privado que entrega Moodle se descarta.

  • El token solo se envía al host de AULA_URL. Si un enlace de archivo apunta a otro sitio, no se descarga.

  • Las URLs con token nunca se escriben en los logs.

  • Los nombres de archivo que vienen de Moodle se sanean para que no puedan escribir fuera de la carpeta del ramo.

  • Para revocar el acceso: en Aula, Preferencias → Claves de seguridad → Reiniciar.

Desarrollo

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Los tests usan un Moodle falso, con respuestas en tests/fixtures/ que siguen el formato de la API real de Aula USM. No necesitan red ni token. La especificación está en SPEC.md.

Hoja de ruta

  • Subir entregas (mod_assign_save_submission), siempre con confirmación explícita

  • Conector remoto (HTTP + OAuth) para usarlo como conector en la app de Claude

  • Publicar en PyPI (pipx install aula-mcp)

English summary

An MCP server that lets Claude (or any MCP client) read your Moodle as a student: courses, upcoming deadlines, assignment briefs and attachments, course files, grades and forum posts. It talks to Moodle's official REST API through the mobile-app web service (no scraping), works with SSO/Microsoft logins via the mobile launch flow, keeps responses compact to save tokens, and is read-only towards Moodle. Built for Aula USM (Universidad Técnica Federico Santa María, Chile) but usable with any Moodle that enables the mobile web service.

Licencia

MIT

Available Tools

11 tools
avisos_y_forosB
Read-only

Últimos avisos y discusiones de los foros de un ramo (los avisos primero). Usa foro_id para un solo foro.

Inputs: ramo (required), limite, foro_id. Returns: result

contactos_ramoA
Read-only

Profesores y ayudantes de un ramo, con su rol y correo (si Moodle lo deja visible).

Inputs: ramo (required). Returns: result

contenido_ramoC
Read-only

Secciones y recursos de un ramo (id de recurso, tipo, nombre y archivos con su tamaño).

Inputs: ramo (required). Returns: result

descargar_materialA
Idempotent

Descarga archivos de un ramo a su carpeta local, en /Aula/<sección>/.

Filtra por recurso_id (de contenido_ramo) o por texto en buscar; todo=true baja todo el ramo. No sobrescribe archivos existentes salvo con sobrescribir=true. Si el ramo no tiene carpeta vinculada y no hay una única coincidencia, responde con candidatos para usar vincular_carpeta.

Inputs: ramo (required), todo, buscar, recurso_id, +1 more. Returns: result

leer_discusionA
Read-only

Mensajes completos de una discusión de foro (discusion_id viene de avisos_y_foros).

Inputs: discusion_id (required). Returns: result

leer_materialA
Idempotent

Lee el contenido de un archivo del ramo (PDF o texto) y además lo deja guardado en su carpeta local.

Úsalo para entender un enunciado, una guía o un apunte. Identifica el archivo por recurso_id (de contenido_ramo o ver_tarea) y, si el recurso tiene varios, por parte del nombre en archivo. Devuelve hasta ~30 000 caracteres; para PDFs largos pide un rango con paginas='3-6'. No extrae imágenes ni fórmulas dibujadas: si hacen falta, abre el archivo de guardado_en.

Inputs: ramo (required), archivo, paginas, recurso_id. Returns: result

listar_ramosA
Read-only

Lista los ramos del estudiante (por defecto solo los vigentes), con su id y la carpeta local vinculada.

Inputs: incluir_pasados. Returns: result

proximas_entregasA
Read-only

Entregas y actividades pendientes con fecha límite en los próximos dias días.

Con incluir_atrasadas también muestra las pendientes vencidas en las últimas 2 semanas. ramo filtra por un ramo.

Inputs: dias, ramo, incluir_atrasadas. Returns: result

ver_notasA
Read-only

Notas. Sin ramo: nota final de cada ramo. Con ramo: cada evaluación con nota, rango, % y comentarios.

Inputs: ramo. Returns: result

ver_tareaA
Read-only

Detalle de una tarea: enunciado, archivos adjuntos del enunciado, fechas (apertura, vencimiento, corte), formato de entrega permitido y el estado de tu entrega (archivos enviados, nota y comentarios).

tarea_id es el recurso_id que dan proximas_entregas o contenido_ramo. Muchas tareas traen el enunciado solo como PDF adjunto: bájalo con descargar_material(ramo, recurso_id=tarea_id).

Inputs: tarea_id (required), ramo. Returns: result

vincular_carpetaA
Idempotent

Vincula un ramo con su carpeta local (ruta absoluta o relativa a AULA_DIR_BASE).

Sin carpeta, solo sugiere carpetas candidatas. No crea carpetas.

Inputs: ramo (required), carpeta. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 11 tools

    Disambiguation4/5

    Each tool targets a distinct resource or action (courses, sections, files, assignments, grades, forums, contacts, folders, deadlines), and the descriptions explicitly chain ids between tools (recurso_id, tarea_id, discusion_id). The only real overlap is descargar_material vs leer_material, since both fetch a file and leer_material also saves it locally, but the descriptions clearly separate 'read content' from 'download to folder'.

    Naming Consistency3/5

    All names are Spanish snake_case, which is consistent, but the verb convention is mixed: actions use ver_/leer_/descargar_/vincular_/listar_, while several retrieval tools are bare noun phrases (contenido_ramo, contactos_ramo, avisos_y_foros, proximas_entregas). Even within the 'list' category, listar_ramos takes a verb while proximas_entregas does not, so the pattern is readable but not predictable.

    Tool Count5/5

    11 tools is well within the sweet spot and each one maps to a concrete Moodle workflow (browse courses, read content, download/read files, check assignments, grades, forums, contacts, link folders). Nothing appears redundant or padding the surface.

    Completeness4/5

    The read-side lifecycle is well covered: courses -> content -> files -> assignments -> grades -> forums -> contacts -> deadlines, with linking of local folders tying it together. The notable gap is write-side: ver_tarea reports the state of 'your submission' but there is no tool to submit an assignment or post a forum reply, which is a dead end for a core Moodle student action.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to interact with Moodle via the official REST API for read-only tasks like listing courses, materials, assignments, submissions, and grades. Uses token-based authentication and emphasizes safe, no-write operations.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI agents read-only access to a learning platform's courses, assignment details and deadlines, and downloadable course files through the official Web Services API. It automatically works around VPN/DPI network blocking and incomplete TLS certificate chains, and deliberately offers no submission or upload tools.
      22 npm
      MIT