Skip to main content
Glama

sernobre-moodle-mcp

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

This project grew out of marcosnahuel/moodle-mcp. What began as a fork has since been rebuilt from the ground up — translated to English, hardened with bug fixes, and reshaped around our own teaching workflow — so it now stands as an independent codebase while keeping the spirit of the original:

  • Rewritten in English — every tool, parameter and error message (the original project was in Spanish);

  • Bug fixes — hardening across the publishing and question-editing flows;

  • A rewritten companion plugin — the original's local_italiciamcp became local_sernobre_mcp, with its own Web Service endpoints.

Credits — our thanks to Marcos Nahuel for creating the original moodle-mcp, which laid the groundwork for this project: https://github.com/marcosnahuel/moodle-mcp

What is this?

sernobre-moodle-mcp is an MCP server in TypeScript/Node.js that exposes a set of tools that an AI agent can call to interact with a Moodle instance:

  • create / update / duplicate / archive courses;

  • manage sections and reorganize content;

  • publish lessons and resources (idempotent);

  • create quizzes from GIFT files;

  • manage students (enrolment, groups, role changes, password resets);

  • query grades, completion, submissions and attempts;

  • create forums, calendar events and send messages;

  • issue badges and read logs.

Besides the TS wrapper, the repository includes a companion Moodle plugin (local_sernobre_mcp) that adds extra Web Service endpoints (e.g. upsert_quiz, upsert_page, add_questions_gift) needed by some tools.

Related MCP server: Moodle MCP Server

Project status

Component

Version

TypeScript wrapper (sernobre-moodle-mcp)

v0.1.0

Moodle plugin (local_sernobre_mcp)

v0.8.8

See CHANGELOG.md for the full history of changes and migration notes.

Features

  • Guaranteed idempotency — publishing the same content twice never creates duplicates.

  • Translated to English — all tools, parameters and error messages are in English (the original project was in Spanish).

  • Bugs fixed — several fixes compared to the original project, notably in the upsert_quiz, upsert_page, add_questions_gift flows and in question editing on Moodle 5.x.

  • Configurable rate limiting, retries and timeout.

  • Structured logging (JSON per line) with automatic token redaction.

  • Companion Moodle plugin with its own Web Service endpoints.

Architecture

┌─────────────┐   MCP (stdio)   ┌──────────────────────┐   HTTPS JSON   ┌──────────────┐
│  AI Agent   │ ───────────────► │ sernobre-moodle-mcp │ ─────────────► │   Moodle     │
│ (Claude, …) │                  │  MCP server          │                │ Web Services │
└─────────────┘                  └──────────────────────┘                └──────────────┘
                                          │ HTTPS JSON
                                          ▼
                              ┌──────────────────────────┐
                              │  local_sernobre_mcp      │
                              │  plugin (extra endpoints)│
                              └──────────────────────────┘

Requirements

  • Node.js ≥ 20

  • A Moodle 4.x or 5.x instance with Web Services enabled

  • A Web Service token for a user with editingteacher or manager permissions

Installation & configuration

1. Prerequisites

  • Node.js ≥ 20 (check with node --version)

  • npm (comes with Node.js)

  • A Moodle 4.x or 5.x instance that you administer

  • A Moodle user with editingteacher or manager permissions on the courses you want to manage

2. Install the wrapper

git clone https://github.com/sernobre/moodle-mcp.git
cd moodle-mcp
npm install
npm run build

This produces the compiled server in dist/ and the sernobre-moodle-mcp binary.

3. Configure environment variables

The server reads its configuration from environment variables. At minimum you must set MOODLE_URL and MOODLE_WS_TOKEN; everything else has sensible defaults.

Variable

Required

Description

MOODLE_URL

Yes

URL of the Moodle instance (must be HTTPS, except in development)

MOODLE_WS_TOKEN

Yes

Moodle Web Service token (see step 4)

MOODLE_WS_TIMEOUT_MS

No

Timeout per request (default: 30000)

MOODLE_WS_MAX_RETRIES

No

Number of retries (default: 3)

MOODLE_WS_RATE_LIMIT_PER_SEC

No

Requests per second limit (default: 10)

MCP_LOG_LEVEL

No

error | warn | info | debug (default: info)

MOODLE_ALLOW_INSECURE

No

true allows HTTP URLs (development only)

Set them in your shell before starting the server:

PowerShell (Windows):

$env:MOODLE_URL = "https://your-moodle.example.com"
$env:MOODLE_WS_TOKEN = "paste-your-token-here"
$env:MCP_LOG_LEVEL = "info"

bash / zsh (Linux, macOS):

export MOODLE_URL="https://your-moodle.example.com"
export MOODLE_WS_TOKEN="paste-your-token-here"
export MCP_LOG_LEVEL="info"

Or create a .env file and load it in your shell (the project does not auto-load .env files — use a dotenv launcher or export them yourself).

4. Configure Moodle (Web Services) — one-time

Follow these steps on the Moodle side before first use:

  1. Site administration → Server → Web services — enable web services and the REST protocol.

  2. Install/update the companion plugin in step 6 below. During the upgrade, Moodle creates the pre-built Sernobre MCP external service with the MCP function allowlist.

  3. Open External services → Sernobre MCP and keep Authorised users only enabled. Add only the dedicated MCP user.

  4. Under Manage tokens, create a token for that user and select the Sernobre MCP service. A token created for another service is not interchangeable.

The pre-built service includes these core functions:

  • core_webservice_get_site_info

  • core_files_upload

  • mod_assign_save_submission

  • mod_assign_submit_for_grading

  • core_course_get_courses_by_field

  • core_course_get_contents

  • core_course_create_courses

  • core_course_update_courses

  • core_course_edit_section

  • core_course_edit_module

  • core_enrol_get_enrolled_users

  • core_calendar_create_calendar_events

  • core_calendar_get_calendar_events

  • core_calendar_update_event_start_day

  • core_calendar_get_allowed_event_types

  • mod_forum_get_forums_by_courses

  • mod_forum_add_discussion

  • all local_sernobre_mcp_* functions declared by the companion plugin

The token user should have a dedicated least-privilege role in the system or relevant course-category context with these capabilities:

  • moodle/course:create

  • moodle/course:update

  • moodle/course:view

  • moodle/course:manageactivities

  • moodle/user:manageownfiles (needed by Moodle core_files_upload for the current token user)

  • mod/assign:submit

  • moodle/course:movesections

  • moodle/course:sectionvisibility (only when calling the deprecated core section show/hide API directly)

  • moodle/question:add

  • enrol/manual:config

  • moodle/calendar:manageentries

  • moodle/calendar:manageownentries

  • moodle/calendar:managegroupentries

  • mod/forum:viewdiscussion

  • mod/forum:startdiscussion

  • webservice/rest:use

mod/forum:pindiscussions is additionally needed when announcements must be pinned. The companion-plugin section endpoint local_sernobre_mcp_update_section requires moodle/course:update; it is the preferred route for MCP section edits. The destructive core_calendar_delete_calendar_events function is intentionally not in the pre-built service.

For another existing Moodle function, open Site administration -> Plugins -> Web services -> External services -> Sernobre MCP -> Functions -> Add functions. Add only functions needed by the deployment; this allowlist does not replace the capability checks of the token user.

Add moodle/category:manage only when the MCP user must manage categories. Course deletion is deliberately not exposed by the built-in service; add core_course_delete_courses manually only after a separate review.

Audit tip: create a dedicated user such as moodle-mcp-bot, assign the minimum role above only where needed, restrict the token by IP when possible, and set a validity date.

5. Start the server

npm start

The server starts, emits a server.start log line, and waits for MCP traffic over stdio. Logs are JSON per line on stderr; tokens are automatically redacted.

6. Install the companion plugin

Some tools need the local_sernobre_mcp Moodle plugin (plugin-companion/local_sernobre_mcp.zip):

  1. Upload/unzip the archive into <moodle-root>/local/.

  2. Go to Site administration → Notifications to complete the install/update. The version bump also registers or updates the pre-built Sernobre MCP service.

  3. Use that service when creating the token. Do not create a second service unless you intentionally want a different function allowlist.

  4. If the server is already running, restart it after updating the plugin.

7. Smoke test

Run the wrapper in a terminal and ask your MCP client to call ws_raw with core_webservice_get_site_info. If you get back your Moodle site name, the wiring is correct. A token error means step 4 needs checking; an HTTP 404 usually means MOODLE_URL has a trailing slash or a /webservice/... suffix (the wrapper appends that itself).

8. Connect an MCP client

Claude Desktop — add this to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

To use your local build instead of the published package, point command at node with args: ["K:\\Formação\\moodle\\moodle-mcp-sernobre\\dist\\index.js"].

Restart Claude Desktop and confirm the moodle server is listed as connected. See the full guide in examples/setup-claude-desktop.md.

Codex (CLI) — Codex configures MCP servers as TOML tables in ~/.codex/config.toml (user-wide) or .codex/config.toml (project-scoped, trusted projects only). You do not run npm start yourself — Codex launches the server as a subprocess.

Run the published package from npm:

[mcp_servers.moodle]
command = "npx"
args = ["-y", "sernobre-moodle-mcp"]
env = { MOODLE_URL = "https://your-moodle.example.com", MOODLE_WS_TOKEN = "paste-your-token-here", MCP_LOG_LEVEL = "info" }
startup_timeout_sec = 20

Or add it with the Codex CLI (recommended — it writes the TOML for you):

codex mcp add moodle --env MOODLE_URL=https://your-moodle.example.com --env MOODLE_WS_TOKEN=your-token -- npx -y sernobre-moodle-mcp

To use your local build instead of the published package, set command = "node" with args = ["K:\\Formação\\moodle\\moodle-mcp-sernobre\\dist\\index.js"].

Notes:

  • Rebuild with npm run build after any source change if you use the local dist/index.js path.

  • Use an absolute path to node if Codex cannot find it on PATH.

  • Rather than hardcoding the token in env, you can forward it from your shell with env_vars = ["MOODLE_WS_TOKEN"] and export it before launching Codex.

  • Verify with codex mcp list; raise startup_timeout_sec if the server boots slowly.

Other MCP clients — configure the client to launch npx -y sernobre-moodle-mcp (or node dist/index.js for a local build) over stdio with the same environment variables. The server exposes its tools via the standard MCP tools/list and tools/call capabilities.

Available tools

Courses

create_course, update_course, duplicate_course, archive_course, list_my_courses, get_course_context

Sections

create_section, update_section, create_sections, delete_sections, move_section, get_sections, update_sections, duplicate_section, reorder_sections, hide_section, release_section

Content

publish_class_lesson, create_activity, update_activity, publish_preview, confirm_preview, delete_resource, generate_video

Assessment

configure_quiz, create_quiz, update_quiz, import_gift, modify_question, get_quiz_questions, publish_exam_lesson

Communication

create_forum, create_forum_announcement, send_moodle_message, get_site_info, get_course_logs

Gradebook

get_grades, get_assign_submissions, get_assignment_config, get_completion, get_quiz_attempts, grade_manually, submit_assignment_file

Students

list_students, enrol_csv, unenrol_student, change_role, groups, reset_password

Other

list_user_badges, create_calendar_event, update_event, delete_event, list_calendar_events, ws_raw

Lesson example

The repository includes a Markdown lesson example in examples/lesson-example.md, used with the publish_class_lesson tool.

Development

npm run dev          # watch build
npm run typecheck    # type checking
npm run test         # unit tests
npm run test:integration  # integration tests (requires Moodle)
npm run build        # production build

Repository structure

src/                    # TypeScript wrapper (MCP server)
  tools/                # tool implementations
  client/               # Moodle Web Services API client
  schemas/              # validation (zod)
  utils/                # idempotency, logging, rate limit, markdown→HTML
plugin-companion/       # Moodle plugin local_sernobre_mcp (PHP)
docs/                   # technical docs and roadmap
examples/               # examples (lesson, Claude Desktop setup)
tests/                  # tests

License

MIT — see LICENSE.

The original code this project is based on belongs to marcosnahuel/moodle-mcp.

Available Tools

45 tools
archive_courseA

Archive (visible=0) or un-archive (visible=1) a course. Non-destructive: data, enrolments and teacher access stay intact. Use it for end-of-year cleanup or hiding a course in preparation.

Inputs: course_id (required), visible.

assign_to_groupA

Add one or more users to a group by group_id.

Inputs: group_id (required), user_ids (required).

change_roleA

Assign a course-level role to a user (student / teacher / editingteacher / manager). Does NOT unassign previous roles — Moodle supports multiple roles per user per context.

Inputs: user_id (required), new_role (required), course_id (required), context_level.

configure_quizA

Create or update a quiz shell (no questions). Idempotent by slug. Default: hidden, unlimited attempts, grade=10, method=highest. The plugin resolves section_num (section number) to section ID internally. Combine with import_gift to populate questions, or use publish_exam_lesson for both in one call.

Inputs: name (required), slug (required), course_id (required), grade, +8 more.

confirm_previewA

Make a previewed section visible to students. Propagates visibility to all modules inside the section. Idempotent.

Inputs: course_id (required), section_id (required), resource_ids.

create_calendar_eventA

Create a calendar event. Default eventtype=course. Set repeat_count>0 to create weekly recurrences. Returns the created event id and metadata.

Inputs: name (required), timestart (required), groupid, location, +5 more.

create_courseA

Create a new Moodle course with a stable idnumber. Throws MOODLE_WS_COURSE_EXISTS if the idnumber is already in use. Default: hidden (visible=false), topics format, 10 sections.

Inputs: fullname (required), shortname (required), idnumber_slug (required), lang, +5 more.

create_forumA

Create or update a forum (discussion, announcement, Q&A, etc.) in a course section. Idempotent by slug. Default: hidden forum of type "general". Requires the plugin companion.

Inputs: name (required), slug (required), course_id (required), intro, +3 more.

create_forum_announcementB

Post a new discussion in a course forum. If forum_id is omitted, uses the course Announcements (type=news) forum.

Inputs: message (required), subject (required), course_id (required), pin, +2 more.

create_groupA

Create a group inside a course. Use assign_to_group to populate it after.

Inputs: name (required), course_id (required), idnumber, description.

create_sectionA

Create a new section in a course with a given name, summary, position and initial visibility. Idempotent by name: reusing an existing section name returns that section instead of creating a duplicate.

Inputs: name (required), course_id (required), summary, visible, +1 more.

delete_eventA

Delete one or more calendar events. Set delete_repeats=true to remove repeat instances as well.

Inputs: event_ids (required), delete_repeats.

delete_resourceA

Delete a Moodle course module by idnumber. By default only deletes MCP-managed idnumbers (mcp: prefix). Use force=true to delete any idnumber. Returns noop if the module does not exist.

Inputs: idnumber (required), course_id (required), force.

duplicate_courseA

Clone a course into a new one (backup+restore under the hood). Defaults copy activities/blocks/filters, NOT users/enrolments/grades. New course is hidden by default.

Inputs: new_fullname (required), new_shortname (required), source_course_id (required), new_idnumber_slug (required), +3 more.

duplicate_sectionA

Duplicate all modules from a source section into a new section in the same course. New section is named per the name param. Idempotent: returns "exists" if a section with that name already exists.

Inputs: name (required), course_id (required), source_section_id (required), visible.

enrol_csvA

Batch-enrol users in a course from a CSV (email,firstname,lastname[,role]). Creates missing users by default with a random temp password. Returns per-row status.

Inputs: course_id (required), csv_content (required), default_role_shortname, create_users_if_missing.

generate_videoA

Generate a short Italian-language video with Google Veo 3.1 and embed it in a new mod_page in Moodle. Requires GEMINI_API_KEY env. Returns { cmid, video_url, page_url }. Takes ~1 minute end-to-end for a lite 8s clip.

Inputs: name (required), prompt (required), courseid (required), idnumber (required), +7 more.

get_assign_submissionsA

Submissions for an assignment (default: only submitted state). Optionally fetch per-user grading status.

Inputs: assign_id (required), status, user_ids, include_status_per_user.

get_completionB

Activity completion status for a user in a course: per cmid, the state (incomplete / complete / complete_pass / complete_fail) plus completion timestamp.

Inputs: user_id (required), course_id (required).

get_course_contextA

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 lesson so the agent knows where it fits.

Inputs: course_id (required), include_recent_lessons.

get_course_logsA

Approximate activity log for a course: per-user firstaccess/lastaccess derived from core_enrol_get_enrolled_users. Flags users active within the last N hours (default 24). Moodle core does not expose a generic activity-log WS.

Inputs: course_id (required), hours_since.

get_gradesA

Get gradebook entries for a user in a course (or for every enrolled user if user_id is omitted). Returns raw/max grade, item name, module type, feedback.

Inputs: course_id (required), user_id.

get_quiz_attemptsA

Quiz attempts for a user on a given quiz. Default: only finished attempts. Set include_review=true to also fetch per-question details (heavier).

Inputs: quiz_id (required), user_id (required), status, include_review.

get_quiz_questionsA

List all questions attached to a quiz (identified by its slug). Read-only. Returns question id, name, type, and slot number for each question.

Inputs: slug (required), course_id (required).

get_site_infoA

Get site + user + token info (core_webservice_get_site_info). Use include_functions=true at bootstrap to verify which plugin WS functions are exposed to the token.

Inputs: functions_filter, include_functions.

grade_manuallyA

Manually grade an assignment submission (mod_assign_save_grade). Feedback text is HTML-safe. Supports team grading and marking workflow state.

Inputs: grade (required), user_id (required), assign_id (required), feedback_text, +3 more.

hide_sectionA

Hide a course section (and its modules) from students. Visibility propagates to all modules inside the section.

Inputs: course_id (required), section_id (required).

import_giftA

Import GIFT-formatted questions into a quiz. Creates the questions in a bank category and appends them to the quiz slots by default. Idempotent (plugin dedupes by question name within the category).

Inputs: course_id (required), gift_text (required), quiz_slug (required), append, +1 more.

list_calendar_eventsB

List calendar events by courses/groups/categories, optionally filtered by a timestart/timeend range.

Inputs: timeend, group_ids, timestart, course_ids, +1 more.

list_my_coursesA

List courses where a user is enrolled. Accepts userid (e.g. obtain from get_site_info for the bot, or pass a student_id-mapped Moodle userid).

Inputs: userid (required), limit, only_visible.

list_studentsA

List enrolled users in a course. Filter by role shortname (default: student). Returns id, fullname, email, lastaccess, roles and groups per user.

Inputs: course_id (required), role, limit.

list_user_badgesA

List badges earned by a user. Optionally filtered by course_id. Read-only — awarding badges is deferred to v0.6.

Inputs: user_id (required), course_id.

modify_questionA

Edit an existing question (typo fix, reformulation, feedback tweak). Writes directly to DB, bypass Moodle 5.0.2 qbank form bug. Input: course_id, question_id, optional name / question_text / answers[]. Coverage: name, text, answers (answer/feedback/fraction).

Inputs: course_id (required), question_id (required), name, answers, +1 more.

publish_class_lessonA

Publish a LessonPlan markdown file as a Moodle section with component modules. Idempotent: republishing the same lesson updates in place, never duplicates. Default mode is hidden. Use publish_preview + confirm_preview for the preview workflow.

Inputs: course_id (required), lesson_path (required), mode, section_id.

publish_exam_lessonA

Create or update a quiz and populate it with GIFT questions in one call. Runs plugin repair+promote steps after import so the quiz is immediately attemptable. Idempotent by (course_id, slug).

Inputs: name (required), slug (required), course_id (required), gift_text (required), +10 more.

publish_previewA

Publish a LessonPlan in hidden preview mode. Returns the same shape as publish_class_lesson plus preview_url the teacher can open to review. Students will not see anything until confirm_preview is called.

Inputs: course_id (required), lesson_path (required).

release_sectionA

Make a course section visible to students (reverse of hide_section).

Inputs: course_id (required), section_id (required).

reorder_sectionsB

Reorder sections in a course. Accepts an array of {section_id, position} and applies the full deterministic layout in one batched call.

Inputs: order (required), course_id (required).

reset_passwordA

Reset a user's password. If new_password is omitted, generates a random strong one and returns it (you MUST forward to the user out-of-band).

Inputs: user_id (required), new_password.

send_moodle_messageA

Send a private Moodle message to one or more user ids. Max 50 recipients per call. Uses core_message_send_instant_messages.

Inputs: text (required), recipients (required), format.

unenrol_studentB

Unenrol one or more users from a course. Non-destructive: user data is preserved, only the course enrolment link is removed.

Inputs: user_ids (required), course_id (required).

update_courseB

Update one or more fields of a course (fullname / shortname / summary / visible / lang / categoryid). At least one field is required.

Inputs: course_id (required), lang, summary, visible, +3 more.

update_eventA

Reschedule a calendar event to a new timestart. To change name/description/location, delete + re-create (Moodle WS does not expose full event update).

Inputs: event_id (required), new_timestart (required).

update_sectionA

Update a course section (name/summary/visible) identified by section_id. At least one field is required. Visibility propagates to all modules inside the section.

Inputs: course_id (required), section_id (required), name, summary, +1 more.

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

    A3.5/5.0

    Scored across 45 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes with detailed descriptions. A few pairs like publish_class_lesson/publish_preview and configure_quiz/publish_exam_lesson overlap partially, but the descriptions explicitly guide which to use and when.

    Naming Consistency4/5

    The vast majority follow a verb_noun snake_case pattern (create_section, list_students, delete_event). Minor inconsistencies exist, such as mixing list_ and get_ prefixes for retrieval operations and the non-conforming ws_raw, but these are infrequent and do not impede readability.

    Tool Count2/5

    With 45 tools, the set is significantly larger than the ideal 3-15 range and exceeds the 25+ threshold where tools become unwieldy for an agent to navigate. While the Moodle domain is broad, many tools are highly granular (e.g., generate_video, reset_password) and the volume feels excessive rather than well-scoped.

    Completeness4/5

    The tool surface covers a wide range of Moodle operations: course CRUD, sections, quizzes, assignments, enrolments, groups, forums, calendar, and messaging. Notable gaps exist, including single-user creation (only via CSV), course deletion (only archive), assignment creation, and badge awarding (explicitly deferred), but these are workable for most core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers