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.

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.