moodle-mcp

Servidor del Protocolo de Contexto de Modelo para Moodle LMS — conecta Hermes, Claude Code y OpenCode a tu Moodle. Obtén tareas, calificaciones y plazos, sincroniza con Obsidian y recibe alertas de WhatsApp.

Resumen • Características • Inicio rápido • Configuración • Configuración del agente • Herramientas • Sincronización con Obsidian

Resumen

moodle-mcp conecta la API de Servicios Web de Moodle con el Protocolo de Contexto de Modelo, para que los agentes de IA puedan actuar como tu asistente académico. Fue construido para Polibatam (filtrado multiclase) pero funciona con cualquier instancia de Moodle que tenga Servicios Web habilitados.

Bifurcación de loyaniu/moodle-mcp — ampliado de 22 a 40 herramientas con sincronización con Obsidian, descargas de materiales, herramientas de entrega, integración de calendario, recuperación concurrente y archivado automático de semestre.

[!TIP] Funciona con cualquier Moodle LMS — solo apunta MOODLE_URL a tu instancia. El filtro de clase de Polibatam (MOODLE_MY_CLASS) es opcional.

Related MCP server: mcp-moodle

Características

• Tareas y plazos — filtradas por franja horaria de clase, ordenadas por urgencia, con listas de tareas accionables

• Calificaciones y progreso — comprobaciones de estado del curso, carga de estudio y seguimiento de finalización

• Contenido del curso y búsqueda — secciones, módulos, materiales, anuncios, actividad reciente

• Sincronización con Obsidian — exportación con un solo comando de paneles, plazos y notas del curso (con archivado automático de semestre)

• Descargas de materiales — listar y descargar archivos del curso y adjuntos de tareas

• Entregas — enviar texto, verificar estado y leer comentarios

• Calendario — eventos próximos, crear recordatorios (H-2), marcar actividades como completadas

• Listo para agentes — único install-mcp.sh para Hermes, Claude Code y OpenCode

Inicio rápido

Instalación en una línea

curl -fsSL https://raw.githubusercontent.com/zuckdorsey/moodle-mcp/main/scripts/install-mcp.sh | bash

Detecta automáticamente los agentes instalados y configura cada uno. Para una simulación:

bash scripts/install-mcp.sh --dry-run

Verificar

# Hermes (profile: akademik)
hermes --profile akademik mcp test moodle
# → ✓ Connected  ✓ Tools discovered: 40

# Claude Code
claude mcp list

# Run tests
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v

[!NOTA] Prefiere fuente local en lugar de PyPI durante desarrollo — el lanzador establece PYTHONPATH en src/ automáticamente.

Configuración

1. Obtén tu token de Moodle

1. Abre https://<tu-moodle>/user/managetoken.php

2. Busca la fila con Servicio web móvil de Moodle en Servicio

3. Copia el token

2. Crea .env

cp .env.example .env

MOODLE_URL=https://your-moodle.example.com/webservice/rest/server.php
MOODLE_TOKEN=your_token_here

# Optional — Polibatam class-slot filter (e.g. Pagi C, Siang A)
MOODLE_MY_CLASS=Pagi C

# Optional — custom vault path
OBSIDIAN_VAULT_PATH=/home/you/Obsidian Vault

3. Instala el paquete

# with uv (recommended)
uv pip install -e .

# or pip
pip install -e .

[!ADVERTENCIA] Nunca subas .env — contiene un token con acceso completo a la API. Ya está en .gitignore.

Configuración del agente

Elige tu agente — todos usan el mismo lanzador local en scripts/moodle_mcp_local_launch.py.

Hermes Agent (recomendado)

bash scripts/install-mcp.sh --agent hermes --profile akademik

Manual (~/.hermes/profiles/akademik/config.yaml):

mcp_servers:
  moodle:
    command: /home/you/Programming/Python/moodle-mcp/.venv/bin/python
    args: [/home/you/Programming/Python/moodle-mcp/scripts/moodle_mcp_local_launch.py]
    env:
      MOODLE_URL: ${MOODLE_URL}
      MOODLE_TOKEN: ${MOODLE_TOKEN}
      MOODLE_MY_CLASS: "Pagi C"
      OBSIDIAN_VAULT_PATH: "/home/you/Obsidian Vault"

Claude Code

bash scripts/install-mcp.sh --agent claude-code
# or manually
claude mcp add -s user moodle-mcp -- python3 /path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py

JSON global (~/.claude/settings.json):

{
  "mcpServers": {
    "moodle-mcp": {
      "command": "python3",
      "args": ["/path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py"],
      "env": {
        "MOODLE_URL": "https://your-moodle/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

OpenCode

bash scripts/install-mcp.sh --agent opencode

~/.config/opencode/config.json:

{
  "mcp": {
    "moodle-mcp": {
      "command": "python3",
      "args": ["/path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py"],
      "environment": {
        "MOODLE_URL": "https://your-moodle/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Desktop / Cursor

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "moodle-mcp": {
      "command": "uvx",
      "args": ["moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

Reinicia la aplicación de escritorio — las herramientas aparecerán en el selector.

Herramientas

40 herramientas en 7 grupos. Llámalas por su nombre desde cualquier agente conectado (ej. "lista mis cursos de Moodle" → get_my_courses).

[!TIP] Prueba: "¿qué tengo que entregar esta semana?" → get_upcoming_deadlines, "analiza tarea base de datos" → analyze_assignment, "sincroniza con Obsidian" → sync_moodle_to_obsidian.

Sincronización con Obsidian

La sincronización crea notas en Academic/Moodle dentro de tu vault:

Obsidian Vault/Academic/
  Moodle/                    ← current semester (always up-to-date)
    .semester_courses.json   ← hidden state (course IDs)
    Dashboard.md
    Deadlines.md
    Grades.md
    Courses/
  Archive/
    Semester-2026-07/        ← auto-created on rollover
      Dashboard.md
      Courses/
      Archive-README.md

Archivado automático de semestre se activa cuando >50% de los IDs de curso cambian (o todos son nuevos). Un intercambio de un solo curso se ignora.

PYTHONPATH=src python - <<'PY'
from moodle_mcp import api
print(api.sync_moodle_to_obsidian())
PY

Notas de seguridad

[!PRECAUCIÓN] Tu token de Moodle otorga acceso completo a la API como tu usuario. Trátalo como una contraseña.

• Los tokens se cargan en el servidor y nunca se envían al modelo.

• Inyecta MOODLE_URL / MOODLE_TOKEN como secretos de entorno en CI.

• moodle.py utiliza un User-Agent similar al de un navegador + POST para compatibilidad con Cloudflare.

Agradecimientos

Bifurcación de loyaniu/moodle-mcp — crédito a todos los contribuyentes originales:

Adiciones en esta bifurcación

• Sincronización con Obsidian + archivado automático de semestre

• Descargas de materiales y adjuntos de tareas

• Herramientas de entrega y comentarios, calendario y finalización

• Filtro de franja horaria de Polibatam (MOODLE_MY_CLASS)

• Recuperación concurrente (~10× más rápido en tareas accionables)

• Universal install-mcp.sh para Hermes / Claude Code / OpenCode