Skip to main content
Glama
Moodle MCP Server
by d1zcipline

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: 5

Why this exists

Two things go wrong on some networks, and both are handled automatically:

  1. A full-tunnel VPN kills TLS, not TCP. The tunnel completes the TCP handshake and then silently drops the ClientHello, so every request ends in ETIMEDOUT even though nc says the port is open. The client binds its sockets to the physical interface (en0/en1 on macOS, overridable with MOODLE_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.

  2. 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.pem and keeps validating against the real system roots — no NODE_TLS_REJECT_UNAUTHORIZED=0 anywhere.

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_app service — 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 install

Configure

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

DPAPI CurrentUser — only this Windows account on this machine can decrypt it

macOS

keychain

a generic-password item in the login keychain

Linux

secret-service

GNOME Keyring / KWallet through secret-tool

anything else

aes-gcm

AES-256-GCM keyed by MOODLE_VAULT_KEY or a 32-byte key file (mode 600)

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 values

The 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

MOODLE_BASE_URL

unset (required)

Moodle site root, no trailing slash

MOODLE_TZ

system time zone

IANA zone used to render due dates

MOODLE_SECRETS_DIR

./.secrets

Where the vault and the TLS cache live

MOODLE_VAULT_BACKEND

auto

Force dpapi, keychain, secret-service or aes-gcm

MOODLE_VAULT_KEY

unset

Passphrase for the aes-gcm backend (scrypt KDF)

MOODLE_ALLOW_HTTP

unset

Set to 1 to allow a plain http:// site (loopback always allowed)

MOODLE_DATA_DIR

./moodle-data

Where downloaded course material goes

MOODLE_LOCAL_ADDR

auto (en0, en1)

Source address to bypass a VPN tunnel

MOODLE_NO_BIND

unset

Set to 1 to never bind a source address

MOODLE_SERVICE

moodle_mobile_app

Web Services shortname used for the token

MOODLE_DEBUG

unset

Set to 1 for request-level logs on stderr

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: false

Claude 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

moodle_whoami

—

name, user id, site release, number of API functions

moodle_courses

—

id — fullname (shortname) list

moodle_course_structure

courseid

markdown outline with due dates and files

moodle_course_module

cmid

module name/type/course, assignment due date and description

moodle_assignment

cmid or assignid+courseid

description, dates, grade, attachments, submission status

moodle_list_files

courseid

file list with sizes and token-free fileurls

moodle_download_file

url, filename?, subdir?

saved path and size

moodle_dump_course

courseid, download?

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

Cannot reach … ETIMEDOUT while the browser works

VPN tunnel drops TLS. node cli.mjs probe shows whether the bound attempt succeeds; set MOODLE_LOCAL_ADDR=<ip> or disable the VPN.

Cannot verify the TLS certificate

The AIA fetch failed (offline / blocked). Delete .secrets/tls-chain.pem and retry on a working network; the root is still verified.

No Moodle credentials stored

Run node cli.mjs vault init (or setup-credentials.sh / setup-credentials.ps1).

No Moodle site configured

Run node cli.mjs vault init, or set MOODLE_BASE_URL for a one-off command.

Cannot decrypt the vault / DPAPI call failed

The vault was copied from another machine or account. Re-run node cli.mjs vault init, or use MOODLE_VAULT_BACKEND=aes-gcm with the original MOODLE_VAULT_KEY.

Refusing a plain http:// site

Use https://; set MOODLE_ALLOW_HTTP=1 only for a throwaway local server.

Wrong Moodle username or password

Moodle rejected the form or login/token.php. Check the account works in the browser.

Cannot get a token: invalidservice

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 fileurl is token-free by design; pass it unchanged to moodle_download_file, which attaches the token. A 403 means the token was revoked — node cli.mjs login.

Empty moodle_list_files

The course may only contain pages, links and forums — check moodle_course_structure.

Run MOODLE_DEBUG=1 node cli.mjs probe for request-level detail.

How it works

File

Role

lib/http.mjs

HTTPS client: source-address binding, AIA chain repair, cookies, redirects, retries

lib/auth.mjs

form login (logintoken), token issue/cache, legacy-vault migration

lib/vault.mjs

encrypted storage: DPAPI, macOS keychain, Secret Service, AES-256-GCM

lib/ws.mjs

REST wrappers (core_course_get_contents, mod_assign_*, core_files_*)

lib/course.mjs

HTML→text, course outline rendering, mirroring to disk

cli.mjs

command line on top of the same library

mcp-server.mjs

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/600 on POSIX and icacls /inheritance:r /grant:r <user>:F on 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, --json payloads and the moodle-data/ dumps lose their token / wstoken / password parameters, 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_DEBUG is stripped of its query string and userinfo before it reaches stderr.

  • node cli.mjs vault destroy --yes removes 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.php with 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 tools
moodle_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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to access a student's EPFL Moodle data—deadlines, course files, assignments, forums, and grades—through read-only tools.
      12
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      8
      MIT