Skip to main content
Glama

mcp-moodle

An MCP server that exposes Moodle Web Services to any MCP-compatible AI assistant — Claude Code, Claude Desktop, Cursor, Codex, and others.

Ask your assistant things like "what's due this week?", "list my courses", "download the slides from CS101 week 3" — without leaving the chat.

Features

  • site_info — verify the token and get the authenticated user

  • list_my_courses — courses you're enrolled in

  • get_course_contents — sections, modules, file URLs

  • search_courses — search the public catalog

  • list_assignments — assignments across one or all courses

  • list_quizzes — quizzes/QCMs in one or all visible courses

  • get_quiz_qcm_content — rendered QCM questions, readable text, and images

  • upcoming_events — calendar deadlines and sessions

  • get_user_grades — your grades for a course

  • download_file — save any Moodle file locally (token appended automatically)

Works with any Moodle 3.5+ instance that has Web Services enabled.

Related MCP server: Moodle MCP Server

Install

The recommended way is uv — no virtualenv to manage:

# One-off run (no install)
uvx mcp-moodle

# Or persist as a tool
uv tool install mcp-moodle

Plain pip works too:

pip install mcp-moodle

Update

If you installed with uv tool install, upgrade to the latest published version with:

uv tool upgrade mcp-moodle

If you run it one-off with uvx, force a fresh fetch with:

uvx --refresh mcp-moodle

For pip installs:

pip install -U mcp-moodle

Get a token

Moodle Web Services require a personal token. The package ships a helper that handles every common login flow — native accounts, SSO (Microsoft, Google, SAML, OAuth), or manual paste:

# Default: opens a Chromium window, you complete SSO, token is captured
uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org

# Native (non-SSO) account
uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org \
  --method local --user jdoe

# Headless server fallback (paste the moodlemobile:// URL by hand)
uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org \
  --method manual-mobile

The token is written to ./.env (chmod 600) as MOODLE_URL and MOODLE_TOKEN. Pass --stdout to print it to stdout instead.

The [token] extra pulls in Playwright. First run downloads Chromium (~150 MB, one-time). Skip the extra if you only ever use --method local, --method web, or --method manual-mobile.

Configure your MCP client

Claude Code

claude mcp add moodle \
  --env MOODLE_URL=https://moodle.example.org \
  --env MOODLE_TOKEN=your_token_here \
  -- uvx mcp-moodle

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "moodle": {
      "command": "uvx",
      "args": ["mcp-moodle"],
      "env": {
        "MOODLE_URL": "https://moodle.example.org",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor / other clients

Any MCP client that supports stdio servers works the same way: command uvx, args ["mcp-moodle"], env MOODLE_URL and MOODLE_TOKEN.

Verify it works

In your MCP client, ask: "call the moodle site_info tool". You should see your name, username, and the site URL.

Quiz / QCM content

Use list_quizzes to find quiz instance ids, then call get_quiz_qcm_content with the quiz id. The tool reuses the latest unfinished attempt when one exists. If no unfinished attempt exists, it returns requires_attempt_creation: true instead of starting an attempt silently; ask the user for permission, then call again with start_if_needed: true.

Each returned question keeps Moodle's raw html and also includes:

  • text — cleaned readable text with formula/image labels from alt/title

  • images — image metadata with the original url and a token-free download_url that can be passed to download_file

download_file automatically converts Moodle pluginfile.php URLs to the token-aware webservice/pluginfile.php form before downloading.

Development

git clone git@github.com:Snaw80/moodle-mcp.git
cd moodle-mcp
uv sync --all-extras
uv run mcp-moodle

Security notes

  • Your token is the equivalent of a password for Moodle Web Services — keep .env out of version control (the included .gitignore already does this).

  • The server reads MOODLE_TOKEN from the environment and never logs it.

  • download_file appends the token to the URL; that URL is not logged either, but be mindful if your client echoes tool arguments.

License

MIT — see LICENSE.

Available Tools

10 tools
download_fileA

Download a Moodle file (from get_course_contents) to a local path.

The Moodle token is appended automatically. The target directory is created if missing.

Args: file_url: pluginfile.php URL from a module's contents[].fileurl save_path: absolute local path to write the file to

Inputs: file_url (required), save_path (required).

get_course_contentsA

Return sections, modules and file URLs for a course.

File URLs returned in contents[].fileurl require the Moodle token appended as ?token=... (or use download_file).

Args: course_id: numeric course id (see list_my_courses)

Inputs: course_id (required). Returns: result

get_quiz_qcm_contentA

Return rendered QCM/quiz questions from the current attempt.

The tool reuses the latest unfinished attempt. If no unfinished attempt exists, it returns requires_attempt_creation=true unless start_if_needed is explicitly true.

Args: quiz_id: quiz instance id (see list_quizzes) start_if_needed: create a new attempt only when no unfinished attempt exists preflight_data: optional Moodle preflight data, e.g. quiz password entries

Inputs: quiz_id (required), preflight_data, start_if_needed.

get_user_gradesC

Return the authenticated user's grades for a course.

Args: course_id: numeric course id

Inputs: course_id (required).

list_assignmentsA

List assignments across given courses (or all enrolled if omitted).

Args: course_ids: optional list of course ids; omit to use all enrolled

Inputs: course_ids.

list_my_coursesA

List courses the authenticated user is enrolled in.

Returns id, shortname, fullname, category id, and visibility.

Inputs: no named parameters. Returns: result

list_quizzesA

List quizzes/QCMs in given courses, or all visible quizzes if omitted.

Args: course_ids: optional list of course ids

Inputs: course_ids.

search_coursesA

Search the public course catalog by keyword.

Args: query: search text page: 0-indexed page perpage: results per page (max 100)

Inputs: query (required), page, perpage.

site_infoA

Return Moodle site info and the authenticated user's id/username.

Use this first to verify the token works.

Inputs: no named parameters.

upcoming_eventsB

Return upcoming calendar events (deadlines, sessions) for the user.

Args: limit: max number of events to return

Inputs: limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Every tool targets a distinct resource or action: file download, course contents, quiz content, grades, assignments, courses, quizzes, search, site info, and events. No two tools have overlapping purposes, and descriptions clearly differentiate them.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (e.g., download_file, get_course_contents, list_assignments). However, site_info and upcoming_events deviate from this pattern, breaking the otherwise consistent naming scheme.

    Tool Count5/5

    With 10 tools covering core Moodle operations (listing courses, assignments, quizzes, retrieving content, grades, events, and file downloads), the count is well-scoped and neither too sparse nor overwhelming for the server's purpose.

    Completeness3/5

    The tool set covers read and listing operations well but lacks write actions such as submitting assignments, creating quizzes, enrolling in courses, or updating user data. This leaves notable gaps for interactive workflows, limiting completeness.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT