Moodle MCP (Aula USM)
# Moodle MCP (Aula USM)
[](https://github.com/muitomou/moodle-mcp-aula-usm/actions/workflows/tests.yml)


Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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.
## 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.
```bash
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:
```bash
.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:
```bash
.venv/bin/aula-mcp-check
```
## Conectarlo a Claude
**Claude Code**
```bash
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:
```bash
.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` → **P**ruebas **d**e **S**oftware, `seminariosisges` → **Seminario** de
**Sis**temas y **Ges**tió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
```bash
.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](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](https://modelcontextprotocol.io) 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](LICENSE)
TDQS
Scored across 11 tools
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'.
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.
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.
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.