moodle-mcp
The moodle-mcp server is an MCP adapter enabling AI agents to comprehensively manage Moodle LMS instances through idempotent Web Service calls. Key capabilities include:
Course & Section Management: Create, update, duplicate, archive, and list courses; retrieve full course context (sections, modules, enrollment stats); create, update, hide/show, and reorder sections.
Content Publishing: Publish markdown-based lessons (
FichaClase) as Moodle sections with a preview-and-confirm workflow (hidden by default, teacher reviews viapreview_urlbefore release). All write operations are idempotent — republishing updates in place, never duplicates.Quiz & Assessment: Publish quizzes (
FichaExamen), configure them, and import questions via GIFT format.Student & Enrollment Management: List students, enroll/unenroll via CSV, create groups, assign users to groups, change roles, and reset passwords.
Gradebook & Performance: Retrieve grades, course completion status, quiz attempts, and assignment submissions; perform manual grading.
Communication & Calendar: Send Moodle messages, create forum announcements, retrieve course logs and site info; create, list, update, and delete calendar events.
Badges: List badges earned by a user (read-only).
Raw Web Services (
ws_raw): Call any Moodle Web Services function directly as an escape hatch when no high-level tool applies.
Note: Full functionality for content publishing and imports requires the companion PHP plugin (
local_italiciamcp) installed on the Moodle instance.
Provides tools for publishing and managing pedagogical content in Moodle courses via Web Services, including creating/updating sections, pages, resources, and activities with guaranteed idempotency.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@moodle-mcp publish a preview of lesson /home/fichas/spanish/a1/u4/l2.md to course 15"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: wrapper v0.5.2 + plugin v0.5.0 — operate Moodle at ~80% from an LLM agent. (v0.5.0 release adds add_questions_gift contract fix; see CHANGELOG.)
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 pluginlocal_italiciamcpthat ships alongside this repo inplugin-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) andws_rawstill work.
Related MCP server: mcp-moodle
Tool catalog (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-mcpRequires Node.js 20 or higher.
Configuration (env vars)
Variable | Required | Default | Description |
| yes | — | Full HTTPS URL of the Moodle instance. |
| yes | — | Web Services token with edit permissions. |
| no |
| Per-request timeout. |
| no |
| Retry attempts on transient failures. |
| no |
| Token-bucket rate limit. |
| no |
|
|
| no |
| Allow |
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
codefields.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 anadvertencia. Installinglocal_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 -vSecurity
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.
Available Tools
5 toolsconfirmar_previewB
Make a previewed section (and optionally a subset of its modules) visible to students. Idempotent.
Inputs: seccion_id (required), recursos_ids.
obtener_contexto_cursoA
Returns a compact radiograph of a Moodle course: metadata, sections with module counts, recent MCP-published lessons, and enrolment counts (teachers vs students). Call this before publishing a Ficha so the agent knows where it fits.
Inputs: course_id (required), incluir_ultimas_clases.
publicar_ficha_claseA
Publish a FichaClase markdown file as a Moodle section with component modules. Idempotent: republishing the same Ficha updates in place, never duplicates. Default modo is oculto (hidden). Use publicar_preview + confirmar_preview for the preview workflow.
Inputs: ficha_path (required), course_id (required), section_id, modo.
publicar_previewA
Publish a FichaClase in hidden preview mode. Returns the same shape as publicar_ficha_clase plus preview_url the teacher can open to review. Students will not see anything until confirmar_preview is called.
Inputs: ficha_path (required), course_id (required).
ws_rawA
Escape hatch: call any Moodle Web Services function with arbitrary parameters. Returns { data } on success, structured meta.code + isError: true on failure. Prefer high-level facades when they cover your use case.
Inputs: function_name (required), params.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct and non-overlapping purpose: obtener_contexto_curso provides course metadata, publicar_ficha_clase publishes a class file, publicar_preview publishes in hidden mode, confirmar_preview makes previews visible, and ws_raw serves as a low-level escape hatch. The descriptions clearly differentiate their roles, with no ambiguity in selection.
Naming is inconsistent with mixed conventions: obtener_contexto_curso and publicar_ficha_clase use Spanish verbs with snake_case, while confirmar_preview and publicar_preview mix Spanish verbs with English terms, and ws_raw is an English abbreviation. There is no uniform pattern across the tool set, making it chaotic and harder to predict.
With 5 tools, the count is well-scoped for the server's purpose of managing Moodle courses. Each tool serves a specific function in the publishing workflow (e.g., preview, confirmation, raw access), and none feel redundant or missing for the apparent scope, making the set appropriately sized.
The tool set covers core workflows for publishing and managing Moodle course content, including metadata retrieval, publishing with preview options, and confirmation. A minor gap exists in lacking direct update or deletion tools for existing content, but agents can work around this using the idempotent publishing tools and the ws_raw escape hatch for other operations.
Maintenance
Related MCP Connectors
Create, edit, translate, and export SCORM eLearning modules from a connected AI assistant.
AI-powered LMS course builder: 89 tools, 17 skills, SCORM/xAPI export, agentic UI
Connect any AI agent to 11+ social platforms: schedule, publish & track posts via hosted MCP.
Create, edit, preview, publish, and manage web pages from MCP-capable AI clients.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Moodle learning management systems through the Moodle REST API. Supports course management, user enrollment, assignments, forums, quizzes, and file operations through natural language.30 npmMIT
- AlicenseAqualityCmaintenanceEnables AI assistants to interact with Moodle via web services, allowing tasks like listing courses, assignments, events, and downloading files.104MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Moodle LMS via the Moodle REST API, supporting management of courses, users, enrollments, grades, and content.1GPL 3.0
- AlicenseAqualityDmaintenanceMCP server for Moodle that lets AI agents publish and manage pedagogical content — courses, lessons, quizzes, forums — via Moodle Web Services with idempotency.45MIT