moodle-mcp

Moodle MCP Server

An MCP server for AI assistants (Claude Code, Cursor, Codex and other stdio clients) on top of the Moodle web services REST API. It is built for teachers: the assistant can see courses, assignments and student submissions, download submission files, and save a grade with feedback, acting as the teacher and only after the teacher confirms. Unlike student-oriented Moodle MCP servers, the focus here is reviewing assignments and grading.

The server works with any Moodle site that has the mobile web service (moodle_mobile_app) enabled: the token is issued the same way as for the Moodle mobile app, so login through an external OAuth provider with a captcha works too.

Prerequisites

• Node.js ≥ 22.
• Google Chrome or Chromium, for the moodle-mcp-login command.
• Mobile app access enabled on the Moodle site (Site administration → Mobile app). To check: <site>/admin/tool/mobile/launch.php should open rather than return an error.

Quick start

The example below uses https://moodle.example.org; replace it with your Moodle address exactly as it appears in the browser (scheme, host, path; a trailing slash does not matter).

1. Log in, once per machine and again whenever a tool returns a login error (Moodle login and server token, in Russian):

   MOODLE_URL=https://moodle.example.org npx -y -p @av-leschinskiy/moodle-mcp moodle-mcp-login
   

   A Chrome window opens: log in to the site as usual and solve the captcha yourself. The command prints Logged in as <name> on <site> and closes the window. Without -p, npx would start the server instead of the login command. Chrome is looked up in PATH; on macOS and Windows, set its path in MOODLE_CHROME.

2. Add the server to your client. Claude Code:

   claude mcp add moodle -e MOODLE_URL=https://moodle.example.org -- npx -y @av-leschinskiy/moodle-mcp
   

   Add -s user to enable it for all projects; without it, only for the current one.

   Codex, with a command or a block in ~/.codex/config.toml:

   codex mcp add moodle --env MOODLE_URL=https://moodle.example.org -- npx -y @av-leschinskiy/moodle-mcp
   

   [mcp_servers.moodle]
   command = "npx"
   args = ["-y", "@av-leschinskiy/moodle-mcp"]
   env = { MOODLE_URL = "https://moodle.example.org" }
   

   Cursor and other clients: a stdio server with the command npx -y @av-leschinskiy/moodle-mcp and the MOODLE_URL variable:

   {
     "mcpServers": {
       "moodle": {
         "command": "npx",
         "args": ["-y", "@av-leschinskiy/moodle-mcp"],
         "env": { "MOODLE_URL": "https://moodle.example.org" }
       }
     }
   }
   

3. Check: ask the assistant "show my Moodle courses".

From a repository clone, use node <clone>/dist/index.js and node <clone>/dist/cli/login.js instead of npx: dist/ is committed, no build is needed.

What's inside

10 tools in total; 3 of them require user confirmation.

Category	Tools	Confirmation	Covers
Site	2	—	who I am, Moodle version, available functions, my courses
Assignments and submissions	4	—	course assignments, participants and submission statuses, what needs the teacher across a course, full submission
Files	1	—	downloading submission files to disk
Grading	3	3	grade and feedback, submission comment, returning a submission for rework

Full list of names

Site

• moodle_list_courses
• moodle_site_info

Assignments and submissions

• moodle_get_submission
• moodle_list_assignments
• moodle_list_pending_submissions
• moodle_list_submissions

Files

• moodle_download_file

Grading

• moodle_add_submission_comment — confirmation
• moodle_revert_submission_to_draft — confirmation
• moodle_save_grade — confirmation

The server acts on your behalf: it sees and changes the same things you do in the Moodle interface. The host asks for confirmation only for writes that students will see: a grade with feedback, a submission comment, returning a submission to draft (destructiveHint: true). Downloading a file also writes, but only to your disk, and needs no confirmation.

Responses are trimmed for the model context: HTML in descriptions and submissions is converted to plain text, times to ISO, a grade that is not set to null, and participant emails are never returned.

Configuration

Variable	Required	Default	Description
MOODLE_URL	yes	—	Moodle site address (wwwroot), e.g. https://moodle.example.org
MOODLE_TOKEN_FILE	—	~/.config/mcp-moodle/token.json	Where moodle-mcp-login saves the token (path is resolved via homedir())
MOODLE_TOKEN	—	—	Web service token override (CI / smoke tests)
MOODLE_TIMEOUT	—	30000	Timeout of a single API request (ms)
MOODLE_CHROME	—	—	Chrome/Chromium binary for moodle-mcp-login (looked up in PATH by default)
MOODLE_DEBUG	—	false	1/true/yes/on enables debug output to stderr and debug level in the host log channel

The token file has 0600 permissions and stores the site address it was issued for: if it does not match MOODLE_URL, the server asks you to run moodle-mcp-login. The server reads the file on every request, so there is no need to restart the host after logging in again. The token is scrubbed from error messages, logs and tool responses (including file URLs).

The Chrome profile used for login is kept separate from your main one (~/.config/mcp-moodle/chrome-profile): site cookies persist, so logging in again often works without a password.

Development

npm install        # also enables the git hooks (.githooks)
npm run dev        # tsx, no compilation
npm run build      # native TypeScript 7 → dist/
npm run verify     # typecheck + lint + tests + docs check
MOODLE_URL=… npm run smoke   # read-only tool chain against a live Moodle

Build only with npm run build: devDependencies contain two compiler versions, details. dist/ is committed; the pre-commit hook builds and stages it, bumps the patch version and regenerates the tables above. Architecture and rules are in AGENTS.md (in Russian).