Skip to content
Back to search

moodle-mcp

Zero-dependency MCP server for the Moodle Web Service API — read-only course, assignment, quiz, deadline and file tools for Claude, Cursor and any MCP client. Actively maintained · v1.3.0 · 8 tools · docs in 10 languages.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/faixiang--moodle-mcp/badge.svg)](/listings/faixiang--moodle-mcp)

HTML

<a href="/listings/faixiang--moodle-mcp"><img src="/api/listings/faixiang--moodle-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

① Get a token

Moodle needs a personal access token. Pick whichever works for your site:

**A. Web UI (recommended, works with SSO accounts)**

1. Log in to your Moodle site 2. Avatar → *Preferences* → *Account* → *Security* → *Manage access keys* 3. *Create*, name it `moodle-mcp`, service = *Moodle mobile web service* 4. Copy the token

**B. Mobile-app service via script (only if your site has local passwords)**

python get_token.py

Walks through `/login/token.php` with the `moodle_mobile_app` service and validates the result. Password input is hidden and never logged. If your account is SSO-only this returns `invalidlogin` — use method A instead.

**C. Environment variables**

MOODLE_URL=https://moodle.your-school.edu
MOODLE_TOKEN=your_token_here

② Configure

Create `config.json` next to `server.py` (or copy `config.example.json`):

{
  "url": "https://moodle.your-school.edu",
  "token": "your_token_here"
}

Environment variables take precedence over the file.

③ Register the server

Claude Desktop / Cursor (`mcp.json`):

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["/absolute/path/to/moodle-mcp/server.py"]
    }
  }
}

Use an absolute path to `server.py`. If you have several Python installs, point `command` at the full interpreter path.

④ Verify

Ask your client to call `moodle_site_info`. A working setup returns the site name, Moodle version and your user record. If it fails, jump to [Troubleshooting](#troubleshooting-).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 298 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="docs/banner.svg" alt="Moodle-MCP" width="100%">
  3. # Moodle-MCP
  4. ### Your Moodle, as tools an AI agent can actually use
  5. Read assignments, deadlines and course files straight out of the Moodle Web Service API — no browser, no scraping, no clicking.
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT License"></a>
  7. <img src="https://img.shields.io/badge/python-3.8%2B-3772FF?logo=python&logoColor=white" alt="Python 3.8+">
  8. <img src="https://img.shields.io/badge/MCP-2024--11--05-8A2BE2" alt="MCP 2024-11-05">
  9. <img src="https://img.shields.io/badge/Moodle-3.x%20%7C%204.x-F98012?logo=moodle&logoColor=white" alt="Moodle 3.x / 4.x">
  10. <img src="https://img.shields.io/badge/dependencies-0-success" alt="Zero dependencies">
  11. <a href="https://github.com/Faixiang/Moodle-MCP/stargazers"><img src="https://img.shields.io/github/stars/Faixiang/Moodle-MCP?style=social" alt="GitHub stars"></a>
  12. <img src="https://img.shields.io/badge/version-1.4.0-1f6feb" alt="Version 1.4.0">
  13. <img src="https://img.shields.io/badge/status-actively%20maintained-brightgreen" alt="Actively maintained">
  14. <p>
  15. <b>English</b> ·
  16. <a href="README.zh-CN.md">简体中文</a> ·
  17. <a href="README.zh-TW.md">繁體中文</a> ·
  18. <a href="README.ja.md">日本語</a> ·
  19. <a href="README.ko.md">한국어</a> ·
  20. <a href="README.es.md">Español</a> ·
  21. <a href="README.fr.md">Français</a> ·
  22. <a href="README.de.md">Deutsch</a> ·
  23. <a href="README.pt-BR.md">Português</a> ·
  24. <a href="README.ru.md">Русский</a>
  25. </p>
  26. </div>
  27. > **Companion skill — [moodle-course-watch](https://github.com/Faixiang/moodle-course-watch)**
  28. > This server is the plumbing; the skill is the workflow on top of it. It diffs new coursework, mirrors missing week
  29. > folders, lists what is still unsubmitted, and walks through the downloaded files with graded key points. It is
  30. > mounted as a git submodule in this repository at [`skill/moodle-course-watch/`](skill/moodle-course-watch/)
  31. > (clone with `--recurse-submodules`), and is also a standalone repo for anyone who wants only the skill.
  32. ---
  33. > **Actively maintained.** Latest release **v1.3.0** (2026-10-27): quizzes are no longer a blind spot —
  34. > `moodle_quiz_status` reads real attempt state and scores. Full [changelog](#changelog-) at the end of this file.
  35. ## Preview 🖥️
  36. <img src="docs/preview.svg" alt="Example MCP session" width="100%">
  37. ---
  38. ## Why this exists 🎯
  39. Moodle powers a large share of universities and colleges worldwide, yet it had no general-purpose MCP server. Scraping it with a headless browser is slow, brittle and tends to trip WAFs — while Moodle itself already ships a stable, documented REST API.
  40. This project is the missing wrapper: **one zero-dependency Python file, ten read-only tools**, working against any Moodle 3.x/4.x site with Web Services enabled.
  41. ```text
  42. No pip install. No node. No browser. Just python server.py.
  43. ```
  44. ## Features ✨
  45. ### Data retrieval
  46. - **Deadline-aware** — assignments split into *due soon*, *overdue* and *no pressure*, with days remaining computed for you
  47. - **Weekly digest** — recent additions + deadlines + overdue in a single call, formatted for direct reading
  48. - **Course files** — section structure and file lists with direct download URLs and modified times, metadata only, nothing downloaded
  49. - **Diagnostics built in** — `moodle_site_info` reports site version, account identity and which functions your token may actually call
  50. ### Engineering
  51. - **Zero dependencies** — Python standard library only (`urllib`, `json`, `ssl`), so nothing pollutes your runtime
  52. - **Single file** — copy `server.py` anywhere; no package layout, no build step
  53. - **stdio JSON-RPC 2.0** — drops into Claude Desktop, Cursor, Marvis or any MCP-compatible client
  54. - **WAF-friendly** — serialised calls with a 150 ms gap, because hammering Moodle gets you `502`
  55. - **Read-only by design** — no submit, enrol, edit or delete endpoint exists in the code
  56. ## Tools 🧰
  57. | Tool | What it does | Arguments |
  58. |---|---|---|
  59. | `moodle_setup_guide` | Step-by-step guide for getting a Moodle web-service token and wiring it into this server (browser UI path, SSO caveat, `config.json` and environment-variable options). Needs no token, so it always works. Call it on first setup or after a `TOKEN_MISSING` error. | — |
  60. | `moodle_config_status` | Self-check of the local configuration: `config.json` path, existence and parse result, `MOODLE_URL` / `MOODLE_TOKEN` environment variables, effective URL, where the token came from and its length. The token itself is masked to the first 4 characters. Needs no token. | — |
  61. | `moodle_site_info` | Validate the token, return site name, Moodle version, current user and the list of web-service functions the account may call (diagnostics). | — |
  62. | `moodle_list_courses` | List every enrolled course with id, shortname and fullname. | — |
  63. | `moodle_recent_updates` | Content added or updated in the last N days (assignments, files, announcements), newest first. | `days` (default 7), `course_ids` |
  64. | `moodle_pending_assignments` | Unsubmitted assignments, split into **due soon** / **overdue** / **no pressure**, with deadline and days remaining. | `ahead_days` (default 14), `course_ids` |
  65. | `moodle_quiz_status` | Per-quiz attempt state straight from `mod_quiz_get_user_attempts`: **submitted** / **in progress** / **never started**, with best score, open–close window, time limit and a *window closed* flag. | `course_ids`, `only_pending` |
  66. | `moodle_course_files` | Section structure and file list for one course, including direct download URLs and modified times. **Metadata only — nothing is downloaded.** | `course_id` |
  67. | `moodle_download_week` | Download one week's files (slides + assignment attachments) into a local folder named after the section — `Week N` when the section title carries a week number, otherwise the section's own title (`Online Judge Questions`, `Project Submission`). Creates folders, verifies sizes, skips files already present. Omit `dest_root` to get the list only. | `course_id`, `week` (e.g. `6` or `"Week 6"`, or `all`), `dest_root` |
  68. | `moodle_weekly_digest` | The one-shot summary: recent additions + due-soon + overdue + counts. Best starting point. | `days` (default 7), `ahead_days` (default 14) |
  69. > `moodle_download_week` only writes to your local disk — it never submits anything to Moodle. File URLs returned by the read tools already carry your token, so they download as-is: treat them as secrets and keep them out of logs, screenshots and public repos.
  70. ## Requirements 📦
  71. | Component | Notes |
  72. |---|---|
  73. | Python | 3.8+ (standard library only) |
  74. | MCP protocol | `2024-11-05` |
  75. | Moodle | 3.x / 4.x with Web Services + REST protocol enabled |
  76. | Account | Holds the `webservice/rest:use` capability |
  77. | Verified against | Moodle 4.3.6, full 435-function grant |
  78. ## Quick start 🚀
  79. ### ① Get a token
  80. Moodle needs a personal access token. Pick whichever works for your site:
  81. **A. Web UI (recommended, works with SSO accounts)**
  82. 1. Log in to your Moodle site
  83. 2. Avatar → *Preferences* → *Account* → *Security* → *Manage access keys*
  84. 3. *Create*, name it `Moodle-MCP`, service = *Moodle mobile web service*
  85. 4. Copy the token
  86. **B. Mobile-app service via script (only if your site has local passwords)**
  87. ```bash
  88. python get_token.py
  89. ```
  90. Walks through `/login/token.php` with the `moodle_mobile_app` service and validates the result. Password input is hidden and never logged. If your account is SSO-only this returns `invalidlogin` — use method A instead.
  91. **C. Environment variables**
  92. ```bash
  93. MOODLE_URL=https://moodle.your-school.edu
  94. MOODLE_TOKEN=your_token_here
  95. ```
  96. ### ② Configure
  97. Create `config.json` next to `server.py` (or copy `config.example.json`):
  98. ```json
  99. {
  100. "url": "https://moodle.your-school.edu",
  101. "token": "your_token_here"
  102. }
  103. ```
  104. Environment variables take precedence over the file.
  105. ### ③ Register the server
  106. Claude Desktop / Cursor (`mcp.json`):
  107. ```json
  108. {
  109. "mcpServers": {
  110. "moodle": {
  111. "command": "python",
  112. "args": ["/absolute/path/to/Moodle-MCP/server.py"]
  113. }
  114. }
  115. }
  116. ```
  117. Use an absolute path to `server.py`. If you have several Python installs, point `command` at the full interpreter path.
  118. ### ④ Verify
  119. Ask your client to call `moodle_site_info`. A working setup returns the site name, Moodle version and your user record. If it fails, jump to [Troubleshooting](#troubleshooting-).
  120. ## Configuration reference ⚙️
  121. | Key | Type | Required | Description |
  122. |---|---|---|---|
  123. | `url` / `MOODLE_URL` | string | yes | Base URL of your Moodle site, no trailing path |
  124. | `token` / `MOODLE_TOKEN` | string | yes | Personal access token from *Manage access keys* |
  125. | `config.json` | file | optional | Read from the directory containing `server.py` |
  126. Precedence: environment variables → `config.json` → error.
  127. ## Usage examples 💬
  128. > "What do I still owe this week?"
  129. The agent calls `moodle_weekly_digest` and gets back a ready-to-read brief:
  130. ```text
  131. ## Due in the next 7 days, not submitted
  132. | CIS225 Data Structures | A10021 Crosswords | 2026-10-29 23:59 | 3 days |
  133. | CIS225 Data Structures | A10022 Cow Jogging | 2026-10-29 23:59 | 3 days |
  134. ## Overdue
  135. | CIS225 Data Structures | A10009 Dancing | 2026-10-11 23:59 | 15 days late |
  136. ## Totals
  137. Submitted/graded: 51 | Outstanding: 25 (due soon 4, overdue 14, other 7)
  138. ```
  139. Other prompts that work well:
  140. | Prompt | Tool it lands on |
  141. |---|---|
  142. | "What new material appeared in CIS225 this week?" | `moodle_recent_updates` |
  143. | "List the files in GER405, don't download anything" | `moodle_course_files` |
  144. | "Which of my courses have nothing overdue?" | `moodle_pending_assignments` |
  145. | "Is my token still valid?" | `moodle_site_info` |
  146. ## Troubleshooting 🤔
  147. <details>
  148. <summary><b><code>invalidlogin</code> when running get_token.py</b></summary>
  149. Your account authenticates through SSO/OIDC only, so `/login/token.php` has no local password to check. Use method A — create the token in *Manage access keys* instead.
  150. </details>
  151. <details>
  152. <summary><b><code>502</code> or connection reset during a call</b></summary>
  153. The site's WAF is rate-limiting you. This server already serialises calls and pauses 150 ms between them; if you still hit it, wait a few minutes and retry, and avoid firing several tools in parallel.
  154. </details>
  155. <details>
  156. <summary><b>Tools return empty lists</b></summary>
  157. Check three things: Web Services and the REST protocol are enabled site-wide; the account has `webservice/rest:use`; and any `course_ids` filter you passed is correct. Run `moodle_site_info` first — if the function list is short, the admin restricted your grant to the mobile subset.
  158. </details>
  159. <details>
  160. <summary><b>Turnitin deadlines are missing</b></summary>
  161. Expected. `turnitintooltwo` is its own module without `mod_assign` semantics and exposes no usable deadline field, so it is the one remaining blind spot. Check those in the web UI.
  162. </details>
  163. <details>
  164. <summary><b>Quiz deadlines are missing from <code>moodle_weekly_digest</code></b></summary>
  165. By design. Quizzes live in `mod_quiz`, not `mod_assign`, so they have their own tool: `moodle_quiz_status` returns attempt state, best score and the open–close window for every quiz.
  166. </details>
  167. <details>
  168. <summary><b>A deadline shows as "not set"</b></summary>
  169. The teacher never configured a due date for that assignment. There is nothing to compute; the item still appears so you don't forget it exists.
  170. </details>
  171. <details>
  172. <summary><b>Garbled characters in Windows terminals</b></summary>
  173. Output is UTF-8. In legacy consoles run `chcp 65001` first, or use Windows Terminal.
  174. </details>
  175. ## Security notes 🔒
  176. - The token is a **credential**. Store it in `config.json` or an environment variable, never in a repo. `.gitignore` already excludes `config.json` and `get_token.log`.
  177. - `get_token.py` never logs the password — only its length — and reads it with `getpass`.
  178. - Every tool is read-only by design, so a leaked token cannot modify or delete coursework through this server. Revoke it from *Manage access keys* if it leaks.
  179. - Do not publish captured HTTP traffic: `wstoken` appears in the request body.
  180. ## Compatibility ✅
  181. | Client / Platform | Status |
  182. |---|---|
  183. | Claude Desktop | Works (stdio server entry) |
  184. | Cursor | Works (`mcp.json`) |
  185. | Marvis | Works (MCP registry) |
  186. | Any MCP client | Works — plain JSON-RPC 2.0 over stdio |
  187. | Windows / macOS / Linux | Works — no platform-specific code |
  188. ## Changelog 📌
  189. | Version | Date | Highlights |
  190. |---|---|---|
  191. | **1.4.0** | 2026-11-02 | Two token-free tools: `moodle_setup_guide` (step-by-step token and wiring instructions) and `moodle_config_status` (config self-check with the token masked). Every `TOKEN_MISSING` error now hands over to them instead of dead-ending. |
  192. | **1.3.0** | 2026-10-27 | New `moodle_quiz_status` — attempt state, best score and time windows read from `mod_quiz_get_user_attempts`. The quiz blind spot is closed; `moodle_weekly_digest` now points to it. |
  193. | **1.2.0** | 2026-10-27 | Week numbering is taken from section titles only. Blocks that carry no week number (`Online Judge Questions`, `Project Submission`) keep their own names instead of being silently renumbered. |
  194. | **1.1.0** | 2026-10-27 | New `moodle_download_week` — pulls a whole week's slides and assignment attachments, verifies size, and skips files that are already on disk. |
  195. | **1.0.0** | 2026-10-27 | First release: six read-only tools over the Moodle REST Web Service, stdlib only. |
  196. ## Roadmap 🗺️
  197. - [x] Quiz deadlines and attempt status — shipped in 1.3.0 via `mod_quiz_get_user_attempts`
  198. - [ ] Turnitin support where the API allows
  199. - [ ] Optional local cache to cut repeated round-trips on large course lists
  200. - [ ] Pagination hints for accounts enrolled in very many courses
  201. - [ ] Submission *status* details (graded / feedback available) — still read-only
  202. - [ ] Non-Moodle LMS adapters sharing the same tool surface
  203. ## Contributing 🤝
  204. Issues and pull requests are welcome. The whole server is one file — read `server.py` top to bottom in a few minutes.
  205. - Keep the zero-dependency rule: standard library only.
  206. - Keep every tool read-only.
  207. - Never commit `config.json`, tokens or captured traffic.
  208. - If you add a tool, document it in the Tools table and in every language's README.
  209. ## Feedback 📢
  210. Bugs and feature requests: [open an issue](https://github.com/Faixiang/Moodle-MCP/issues).
  211. ## License 📝
  212. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.