moodle-mcp

Model Context Protocol (MCP) server for Moodle. Lets AI agents publish and manage pedagogical content — lessons, resources, activities — in Moodle via Web Services with guaranteed idempotency.

Status: v0.5.0 — operate Moodle at ~80% from an LLM agent.

What it is

moodle-mcp is a stdio-based MCP server that exposes 40 high-level facades plus one low-level ws_raw escape hatch to run almost the entire teaching workflow of a Moodle course from an AI agent: courses, sections, content (pages, urls, assignments, forums, videos), quizzes (with GIFT import), students (enrolment CSV, groups, roles, passwords), gradebook, messaging, calendar, and badges. Every write is upsert-by-idnumber, so republishing the same Ficha never creates duplicates.

Primary consumer: Claude Desktop driving the Italicia language-teaching workflow. But it is a generic open-source adapter — any MCP-capable agent + any Moodle 4.x/5.x instance with Web Services enabled can use it.

Plugin companion required for full feature set. Upsert of page, url, assign, quiz, file uploads and GIFT imports go through the small PHP plugin local_italiciamcp that ships alongside this repo in plugin-companion/. Install it once (as "Complemento local" in the Moodle admin UI) and expose its functions to the external service the token belongs to. Without the plugin, the read-only facades (list students, grades, calendar, site info) and ws_raw still work.

Tool catalog (v0.5.0 — 40 tools + ws_raw)

Grouped by domain family. Each family lives under src/tools/<family>/.

Curso

crear_curso · actualizar_curso · duplicar_curso · archivar_curso · listar_mis_cursos · obtener_contexto_curso

Secciones

crear_seccion · actualizar_seccion · ocultar_seccion · liberar_seccion · reordenar_secciones

Contenido

publicar_ficha_clase · publicar_preview · confirmar_preview · generate_video (Gemini Veo)

Evaluación (quizzes)

publicar_ficha_examen (one-shot) · configurar_quiz · importar_gift

Alumnos

listar_alumnos · matricular_csv · dar_baja · crear_grupo · asignar_a_grupo · cambiar_rol · reset_password

Gradebook

obtener_calificaciones · obtener_completion · obtener_intentos_quiz · obtener_entregas_assign · calificar_manualmente

Comunicación

enviar_mensaje_moodle · crear_anuncio_foro · obtener_logs_curso · obtener_info_sitio

Calendario

crear_evento_calendario · listar_eventos_calendario · actualizar_evento · eliminar_evento

Badges (read-only)

listar_badges_usuario

Primitive

ws_raw — call any Moodle WS function directly when no facade covers the case.

Deferred to v0.6 (require new plugin endpoints)

duplicar_seccion, crear_banco_preguntas, editar_preguntas_banco, liberar_quiz, ocultar_quiz, otorgar_badge.

Installation

# Via npx (recommended for Claude Desktop)
npx -y @nahuelalbornoz/moodle-mcp

# Or install globally
npm install -g @nahuelalbornoz/moodle-mcp

Requires Node.js 20 or higher.

Configuration (env vars)

| Variable | Required | Default | Description | |---|---|---|---| | MOODLE_URL | yes | — | Full HTTPS URL of the Moodle instance. | | MOODLE_WS_TOKEN | yes | — | Web Services token with edit permissions. | | MOODLE_WS_TIMEOUT_MS | no | 30000 | Per-request timeout. | | MOODLE_WS_MAX_RETRIES | no | 3 | Retry attempts on transient failures. | | MOODLE_WS_RATE_LIMIT_PER_SEC | no | 10 | Token-bucket rate limit. | | MCP_LOG_LEVEL | no | info | error / warn / info / debug. | | MOODLE_ALLOW_INSECURE | no | false | Allow http:// URLs (dev-only escape hatch). |

Claude Desktop config

Add to claude_desktop_config.json (see examples/setup-claude-desktop.md for the exact path per OS):

{
  "mcpServers": {
    "moodle": {
      "command": "npx",
      "args": ["-y", "moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle.example.com",
        "MOODLE_WS_TOKEN": "your-ws-token"
      }
    }
  }
}

Restart Claude Desktop. The five tools above should now be available to the agent.

Examples

1. Snapshot a course before acting

// tool call
{
  "name": "obtener_contexto_curso",
  "arguments": { "course_id": 42, "incluir_ultimas_clases": 5 }
}

Response (abridged):

{
  "course": { "id": 42, "fullname": "Italiano A1", "shortname": "ITA-A1", "format": "topics", "startdate": 1700000000 },
  "secciones": [{ "id": 100, "name": "Unidad 3", "section": 3, "visible": true, "modules_count": 6 }],
  "ultimas_clases": [{ "seccion_id": 100, "seccion_name": "Unidad 3", "ficha_idnumber": "mcp:a9993e364706816aba3e2571" }],
  "matriculados": { "total": 18, "docentes": 1, "alumnos": 17 }
}

2. Publish a FichaClase (preview first)

{
  "name": "publicar_preview",
  "arguments": {
    "ficha_path": "/home/alicia/fichas/italiano/a1-2026/u3/c5.md",
    "course_id": 42
  }
}

Response includes preview_url Alicia can open to review. Once approved:

{
  "name": "confirmar_preview",
  "arguments": { "seccion_id": 100, "recursos_ids": [501, 502, 503] }
}

3. Escape hatch — call a raw WS function

{
  "name": "ws_raw",
  "arguments": {
    "function_name": "core_webservice_get_site_info",
    "params": {}
  }
}

Response:

{ "data": { "sitename": "Aula Italicia", "release": "5.0.2+", ... } }

Idempotency

Every resource created by this MCP carries a stable idnumber of the form:

mcp:<first 24 chars of sha1(ficha.id + "|" + component_id)>

Republishing the same Ficha finds the existing resource by idnumber and updates it in place. Nothing gets duplicated. Safe to retry anywhere, anytime.

v0.1 caveats

v0.1 is honest about its capability boundary. It reliably:

• Looks up a course, its sections and modules.
• Finds "owned" resources by the mcp: idnumber prefix.
• Updates visibility of pre-existing modules (the preview → confirm workflow).
• Surfaces structured Moodle errors with stable code fields.
• Never logs tokens, never propagates stack traces.

v0.1 does not yet:

• Upload asset files via multipart to the Moodle draft file area. Calls planned for asset upload are reported back in advertencias — seed them manually the first time.
• Create brand-new sections or modules through Web Services. Where a module does not exist yet, the tool returns status "missing" plus an advertencia. Installing local_wsmanagesections (or equivalent) and wiring those endpoints is v0.2 work.

Both gaps are driven out by the integration suite in tests/integration/ when run against a real Moodle docker.

Development

git clone https://github.com/marcosnahuel/moodle-mcp
cd moodle-mcp
npm install

npm run typecheck         # tsc --noEmit
npm test                  # vitest unit suite
npm run test:coverage     # with v8 coverage (≥80% enforced)
npm run build             # tsup → dist/

# Integration — requires docker
docker compose -f tests/integration/docker-compose.test.yml up -d
export MOODLE_TEST_URL=http://localhost:8081
export MOODLE_TEST_TOKEN=<generate in Moodle admin>
export MOODLE_TEST_COURSE=<course id>
npm run test:integration
docker compose -f tests/integration/docker-compose.test.yml down -v

Security

• The token is never logged. Tokens appearing in any field of any log record are replaced with ***.
• URLs in error messages are likewise redacted.
• HTTPS is required unless MOODLE_ALLOW_INSECURE=true (dev-only).
• The MCP only talks to Moodle via Web Services REST. No cookie auth, no web scraping, no direct DB access.

Contributing

See CONTRIBUTING.md for issue, PR and commit conventions.

By participating in this project you agree to abide by the CODE_OF_CONDUCT.md.

License

MIT © 2026 Italicia — see LICENSE.