Moodle MCP Server
Provides read-only access to Moodle courses, assignments, deadlines, course structures, and files. It can list courses, inspect course modules and assignment details, list and download course files, and mirror an entire course to disk.
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 Server list my Moodle courses and any upcoming assignment deadlines"
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
MCP server and CLI for Moodle: read courses, assignments, deadlines and files from the terminal or straight from an AI agent — no browser automation, no scraping of interactive pages in the common case.
It talks to the official Moodle Web Services API (core_course_get_contents,
mod_assign_get_assignments, …), falls back to the session-cookie HTML flow when a site restricts
the mobile service, and works around two network problems that break naive clients.
$ node cli.mjs courses
101 Introduction to Data Engineering
102 Academic English
$ node cli.mjs cm 12345
Module 12345: Example practical task
type: assign
course: 101
due: —
max grade: 5Why this exists
Two things go wrong on some networks, and both are handled automatically:
A full-tunnel VPN kills TLS, not TCP. The tunnel completes the TCP handshake and then silently drops the
ClientHello, so every request ends inETIMEDOUTeven thoughncsays the port is open. The client binds its sockets to the physical interface (en0/en1on macOS, overridable withMOODLE_LOCAL_ADDR) instead of the tunnel and the site answers in ~400 ms. Browsers are usually unaffected because their traffic is shaped differently — so "it works in my browser" does not mean a script can reach it.The server sends an incomplete certificate chain. Only the leaf is returned, signed by an intermediate that is not in Node's bundled root store (
UNABLE_TO_VERIFY_LEAF_SIGNATURE), while curl and browsers quietly fetch the missing link. The client reads the AIA "CA Issuers" URL from the leaf, downloads that intermediate, caches it in.secrets/tls-chain.pemand keeps validating against the real system roots — noNODE_TLS_REJECT_UNAUTHORIZED=0anywhere.
Both workarounds are no-ops on a normal network: binding falls back to a plain connection, and the chain is only fetched when Node actually complains about it.
Related MCP server: moodle-mcp
Requirements
Node.js 18 or newer
An account on a Moodle site with Web Services enabled (the standard
moodle_mobile_appservice — most universities have it for the mobile app) and, preferably, the Moodle mobile service enabled for your role.
Install
git clone https://github.com/d1zcipline/moodle-mcp.git
cd moodle-mcp
npm ci # or: npm installConfigure
Credentials are sealed in an encrypted vault (.secrets/moodle.vault.json) and are never written
to disk in plaintext. The vault uses the strongest backend the host offers:
Host | Backend | What protects the values |
Windows |
| DPAPI |
macOS |
| a generic-password item in the login keychain |
Linux |
| GNOME Keyring / KWallet through |
anything else |
| AES-256-GCM keyed by |
node cli.mjs vault init # asks for site URL, login and password (the password is not echoed)
node cli.mjs vault status # backend, paths and whether plaintext is left — never the valuesThe site URL, the login, the password and the cached Web Services token all live inside the vault. Nothing sensitive is passed on the command line, so nothing lands in the shell history or in the process list.
baseUrl comes from the vault unless MOODLE_BASE_URL is set; there is no built-in default site.
Upgrading from a version that used .secrets/moodle.json: run node cli.mjs vault migrate — it
encrypts the plaintext files, verifies the vault and then shreds them.
Environment variables:
Variable | Default | Meaning |
| unset (required) | Moodle site root, no trailing slash |
| system time zone | IANA zone used to render due dates |
|
| Where the vault and the TLS cache live |
| auto | Force |
| unset | Passphrase for the |
| unset | Set to |
|
| Where downloaded course material goes |
| auto ( | Source address to bypass a VPN tunnel |
| unset | Set to |
|
| Web Services shortname used for the token |
| unset | Set to |
CLI
node cli.mjs probe # is the site reachable at all, with and without the bind
node cli.mjs login # sign in, print name and available API functions
node cli.mjs courses # my courses
node cli.mjs tree <courseid> # course outline as markdown
node cli.mjs cm <cmid> # one module by id= from a Moodle URL
node cli.mjs assign <cmid> # assignment JSON incl. submission status
node cli.mjs files <courseid> # every downloadable file
node cli.mjs dump <courseid> # mirror the whole course into ./moodle-data/<courseid>dump writes structure.md, course.json, summary.json, every course file under files/, and
one folder per assignment with its description and attachments. Re-running it skips files whose
size already matches, so it is cheap to repeat. Flags: --json, --no-download, --out DIR.
MCP
The server speaks stdio and exposes eight read-only tools.
DeepSeek Harness (~/.dsh/profiles/desktop/cordis.patch.yml):
- insert:
- id: mcp-moodle
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: moodle
transport: stdio
command: node
args: [/absolute/path/to/moodle-mcp/mcp-server.mjs]
cwd: /absolute/path/to/moodle-mcp
failOnStartupError: falseClaude Desktop (claude_desktop_config.json) and most other clients:
{
"mcpServers": {
"moodle": {
"command": "node",
"args": ["/absolute/path/to/moodle-mcp/mcp-server.mjs"],
"env": { "MOODLE_BASE_URL": "https://moodle.yourschool.edu" }
}
}
}Ready-to-copy files are in examples/.
Tools
Tool | Arguments | Returns |
| — | name, user id, site release, number of API functions |
| — |
|
|
| markdown outline with due dates and files |
|
| module name/type/course, assignment due date and description |
|
| description, dates, grade, attachments, submission status |
|
| file list with sizes and token-free |
|
| saved path and size |
|
| mirror of the whole course on disk |
There are deliberately no submission or upload tools: an agent can read everything and change nothing in Moodle.
What it stores
moodle-data/<courseid>/
structure.md human-readable course outline
course.json raw sections/modules from the API
summary.json what was downloaded into this folder
files/<section>/<file> course files
assignments/<cmid>-<name>/
intro.md description, dates, grade, attachments
assignment.json raw assignment + submission status
files/<file> attachments.secrets/ holds the encrypted vault (site URL, login, password and the Web Services token) plus
the cached TLS intermediate. It is git-ignored, never written into moodle-data/, and nothing in
it is readable as text — see Security.
Troubleshooting
Symptom | Cause and fix |
| VPN tunnel drops TLS. |
| The AIA fetch failed (offline / blocked). Delete |
| Run |
| Run |
| The vault was copied from another machine or account. Re-run |
| Use |
| Moodle rejected the form or |
| The mobile Web Services service is disabled — ask the Moodle admin, or the client falls back to cookie mode. |
Tools return data but file downloads 403 | The |
Empty | The course may only contain pages, links and forums — check |
Run MOODLE_DEBUG=1 node cli.mjs probe for request-level detail.
How it works
File | Role |
| HTTPS client: source-address binding, AIA chain repair, cookies, redirects, retries |
| form login ( |
| encrypted storage: DPAPI, macOS keychain, Secret Service, AES-256-GCM |
| REST wrappers ( |
| HTML→text, course outline rendering, mirroring to disk |
| command line on top of the same library |
| stdio MCP server, eight read-only tools |
The token is cached; when Moodle invalidates it the client re-authenticates once and retries the call, so a long-running MCP server survives password rotations and session timeouts.
Security
The site URL, login, password and Web Services token exist only in the encrypted vault. Windows keeps them behind DPAPI (
CurrentUser), macOS behind the login keychain, Linux behind the Secret Service; the files on disk hold ciphertext or a keyring reference, never the values.Everything the tool creates is restricted to the current user:
chmod 700/600on POSIX andicacls /inheritance:r /grant:r <user>:Fon Windows. That is defence in depth — the ciphertext is already bound to the account.Anything that leaves the process is cleaned first: URLs in MCP tool output,
--jsonpayloads and themoodle-data/dumps lose theirtoken/wstoken/passwordparameters, so a course dump stays shareable and a transcript never carries a credential. The downloader re-attaches the token internally.Credentials and the token only travel in request bodies. Nothing sensitive goes into a query string, so it cannot leak into Moodle access logs or proxy logs, and every URL printed by
MOODLE_DEBUGis stripped of its query string and userinfo before it reaches stderr.node cli.mjs vault destroy --yesremoves the credentials and the token cache; revoke the token itself in Moodle → Preferences → Security → Keys.The client never disables certificate verification and never follows links outside the configured Moodle host for authentication.
Downloads are plain HTTP GETs against
pluginfile.phpwith the Web Services token attached by the client.
License
MIT — see LICENSE.
Not affiliated with Moodle Pty Ltd or any university. Use it on accounts you are allowed to use.
Available Tools
8 toolsmoodle_assignmentC
Full assignment: description, due/cutoff dates, max grade, attachments with download URLs, and my submission status (new/draft/submitted, graded or not, can I still submit).
Inputs: cmid, assignid, courseid.
moodle_course_moduleA
One course module by cmid — the numeric id= in a Moodle URL such as /mod/assign/view.php?id=12345. Returns name, type, course id and, for assignments, the due date and description.
Inputs: cmid (required).
moodle_coursesA
List my enrolled courses as "id — fullname (shortname)". Start here: every other tool needs a course id or a module id taken from it.
Inputs: no named parameters.
moodle_course_structureA
Course outline as markdown: sections, every module (assignment, file, page, url) with its type, due dates and attached files. Use it to see what the course contains before downloading anything.
Inputs: courseid (required).
moodle_download_fileA
Download one file into the local moodle-data/downloads folder and return its path. Takes a fileurl from moodle_list_files or an assignment attachment.
Inputs: url (required), subdir, filename.
moodle_dump_courseA
Mirror a whole course to disk: structure.md, course.json, every file and every assignment with its description and attachments. Saved to moodle-data/. Idempotent — already downloaded files are skipped by size.
Inputs: courseid (required), download.
moodle_list_filesA
Every downloadable file in a course: section, module, filename, size and a direct fileurl. Pass that url to moodle_download_file.
Inputs: courseid (required).
moodle_whoamiA
Signed-in user: full name, user id, site name/release and the number of API functions available.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct roles: discovery (whoami, courses), inspection (structure, module, assignment), and downloading (list_files, download_file, dump_course). There is some natural overlap between course_structure/course_module and list_files/dump_course, but the descriptions explicitly explain when to use each and how they chain together.
All names use the same lowercase snake_case style with a consistent moodle_ prefix, which makes them easy to scan and group. The suffix pattern is not strictly verb_noun throughout (whoami, courses, assignment are noun-like), but the overall convention is predictable.
Eight tools is well-scoped for a Moodle course-content server, with separate tools for authentication, course discovery, structure inspection, file listing, single-file download, and bulk mirroring. Each tool appears to earn its place without excessive fragmentation.
The read/download lifecycle is well covered: user context, courses, structure, modules, assignments, files, single downloads, and full-course mirroring. Minor gaps remain around write/submission actions and broader Moodle areas like grades or forums, especially since moodle_assignment reports whether the user can still submit but provides no way to submit.
Maintenance
Related MCP Connectors
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
Read-only access to Epivo's live course catalogue for AI agents.
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
PLATO (Pusan National University LMS) MCP server via Moodle Web Service API + ubboard scraping
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables Claude to interact with Moodle via the official REST API for read-only tasks like listing courses, materials, assignments, submissions, and grades. Uses token-based authentication and emphasizes safe, no-write operations.2MIT
- AlicenseAqualityCmaintenanceEnables AI agents to access a student's EPFL Moodle data—deadlines, course files, assignments, forums, and grades—through read-only tools.12MIT
- AlicenseAqualityBmaintenanceEnables AI apps to read a student's Moodle courses, upcoming and overdue due dates, assignment submission statuses, course grades, gradebook items and announcements. It is strictly read only, so it can never submit, edit or delete anything.17206 npmMIT
- AlicenseAqualityCmaintenanceProvides read-only access to a university's Moodle virtual campus, letting an AI assistant browse courses, sections and files, check upcoming deadlines, view assignment status and grades, and read forum announcements and threads. Authentication uses a Moodle token stored locally, with support for both undergraduate and postgraduate campus URLs.8MIT