moodle_local
moodle_local is an MCP server for checking Moodle access, selecting approved courses, listing/downloading course materials, and synchronizing them locally while preserving prior versions.
Check Moodle connection and the dedicated login session without exposing credentials.
List enrolled My Modules courses, including hidden courses.
List visible resources for an approved course.
Download a discovered file/folder module from an approved course into the approved materials directory, keeping old versions.
Run a manual incremental sync for locally approved courses, with an option to force content checks by bypassing ETag validation.
Show approved course IDs and local output directories without authentication data.
Replace the local approved course selection after user approval; an empty list clears selection without deleting files.
Confirm setup approval for the current data root; it does not migrate data.
Provides tools for accessing and synchronizing selected UNNC Nottingham Moodle courses, including checking login status, listing courses and resources, selecting course whitelists, downloading course materials, and performing incremental syncs while preserving version history.
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_local check Moodle login status, then sync my selected course files"
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.
Overview
Download materials from selected courses, organize them by course and Moodle section, and keep them up to date through Codex. Previous versions and local annotations are preserved.
Requirements: macOS + Google Chrome, or experimental Windows + Microsoft Edge, and Node.js 24+. This is an unofficial project for UNNC / Nottingham Moodle. Synchronization is manual. Windows + Edge has experimental adaptations, pending real Windows validation; other Moodle installations have not been verified.
Related MCP server: moodle_math_mcp
Installation
To human
Download the ZIP attachment with the highest version number from Releases, then extract it to a permanent program directory.
On macOS open
scripts/setup.command; on Windows openscripts/setup.cmd(experimental). The launcher checks prerequisites, installs dependencies with your confirmation, builds the server, and starts setup.Sign in to Moodle in the dedicated browser, complete MFA, select your courses, and choose how to save materials: automatic course/section folders or your existing folders. The final step recommends installing the Codex skill; press Enter to accept or enter n to skip.
Follow Connect to Codex, then restart Codex and choose a usage mode.
Setup does not download course materials. Existing-folder mappings are confirmed in Codex before downloading unclassified resources.
To agent
Open Codex in the extracted program directory and send:
Help me install and connect this UNNC Moodle MCP. Read the README first, check my environment, and install the project dependencies and bundled skill. Preserve my existing Codex configuration. Ask me to choose courses and the saving mode; I will complete Moodle login and MFA myself. Show me the MCP configuration change for confirmation before applying it. Do not start downloading until I confirm the courses, directories, and any classification rules.
For the agent: locate the downloaded project; if it is absent, guide the user to the ZIP installation above. Check Node.js 24+ and the required browser, then run these commands in the program directory after installation authorization:
npm run doctor
npm ci
npm run buildHave the user run npm run setup in an interactive terminal and complete login/MFA. Explain the two saving modes in Usage. Unless the user opts out, include skill installation; if setup skipped it and installation is authorized, run npm run install-skill -- --yes and check the result. Do not overwrite a conflicting installed skill. Finish Connect to Codex separately, preserving other MCP entries; skill installation alone does not connect MCP. After restarting Codex, read settings and login status back before the first synchronization.
Update
Run this command in your existing program directory:
npm run updateThe updater downloads the newest published release, installs dependencies, and builds it before replacing the existing program. The installation path, settings, login session, and downloaded materials are retained. A failed replacement rolls back to the previous program.
Stop all old Moodle MCP/CLI processes before updating. On first startup, version 0.4.5 moves legacy management files into _moodle beside materials; see storage migration and recovery. Reconnect the Moodle MCP server or restart Codex after updating. Then continue synchronization in Codex. Program updates preserve separately installed skills; run npm run install-skill if you previously skipped installation.
Reinstalling older versions: if npm run update is unavailable or the installed version cannot be upgraded directly, stop the old MCP server and reinstall using the installation steps above. Preserve the materials directory, _moodle (or legacy state and courses.json), and existing settings; remove only the program files. If program and data share a directory, back up the data separately before removing it. Use the previous program path where possible; otherwise update the MCP configuration to the new path. Existing materials do not need to be downloaded again.
The updater supports ZIP installations. Git checkouts must be updated through Git. Published prereleases are included in version selection; drafts are excluded. Network failures should be retried after connectivity is restored.
Connect to Codex
From the program directory, run:
npm run codex-configAdd the printed [mcp_servers.moodle_local] block to your Codex MCP configuration, preserving other entries. This command prints configuration; it does not edit it. The server starts with node /absolute/project/dist/src/server.js.
Setup offers the recommended skill installation on macOS and Windows. Existing users can run npm run install-skill separately; it does not require school login. The installer uses ~/.agents/skills/unnc-moodle, reuses an existing legacy ~/.codex/skills/unnc-moodle, or uses CODEX_HOME/skills/unnc-moodle when configured. Identical installations are left alone; differing or unsafe existing skills are not overwritten. Back up a differing skill outside the skills directory and review it before replacing it. A skill conflict does not undo completed MCP setup. The supplied skill instructions are in Chinese; the MCP tools accept the same requests in English or Chinese.
Restart Codex, then check get_sync_settings and check_connection. Downloads require a confirmed materials directory and selected courses. If login has expired, ask Codex to open the dedicated login browser using the login MCP tool. Complete sign-in and MFA in that browser; Codex verifies the result before continuing. The tool waits up to five minutes. npm run login remains a fallback for clients without the tool.
Usage
Choose either saving mode below. New users choose during setup; existing users can ask Codex to change the mode without reinstalling.
1. Create course folders automatically
Choose the automatic course/section mode during setup, then tell Codex:
Check my Moodle connection and settings, then synchronize my selected courses using automatic course/section folders.
Materials appear under materials/Course name/Moodle section/Resource title.ext. Single-file resources use Moodle titles, such as Seminar 1.pdf and Seminar 1 (Solutions).pdf; folder children retain their filenames and nested structure.
2. Use your existing folders
Choose the existing-folder mode during setup and enter the shared root of your course folders. If already installed, tell Codex:
My course materials are already organized at “PASTE YOUR FOLDER PATH”. Use the existing structure, with lectures in Lecture and seminars in Seminar. First inspect the folders and my selected Moodle resources, then show me the proposed mapping. Save the rules and download only after I confirm. Preserve existing files and notes.
Codex reviews actual resource titles, available page descriptions, and the folders you authorize it to inspect. Confirm or correct the proposed mapping once; saved rules are reused on later synchronizations and after restarting. Different resources within the same Moodle section can go into different folders. Unmatched or ambiguous new resources are skipped for confirmation; after a file is classified, its folder is retained even if the resource is renamed. To correct its classification, confirm an explicit resource assignment.
Target folders must already exist under a shared root. Moving a mapped folder causes a reported failure until the rule is updated. Rules match user-confirmed keywords or specific resources; they do not infer categories from page order or file type, or analyze PDF contents. Existing-folder mode initially has no rules, so unclassified materials are not downloaded.
Existing files are not automatically adopted or deduplicated. A newly downloaded file with the same name receives a suffix, which can leave duplicates; original files and annotations are preserved. Changing the output root does not migrate old materials. Historical versions remain in the original materials/.history.
After either mode is configured, use these requests:
Task | Codex request |
Synchronize materials | “Synchronize my selected Moodle courses.” |
Download newly discovered materials | “Run a quick synchronization of my Moodle courses.” |
Organize existing downloads | “Organize my existing Moodle materials without downloading them again.” |
Add a course | “Show my Moodle courses so I can select another course to synchronize.” |
Synchronization defaults to quick mode. Quick synchronization discovers new files but does not check remote changes to previously recorded files. Full synchronization checks updates. Organize mode refreshes tracked local copies without downloading materials; it can rename unedited legacy files using Moodle titles, while keeping annotated copies separately. Additional courses require your approval. Check failures and skipped resources before treating a synchronization as complete.
MCP synchronization returns a task ID immediately. Codex polls get_sync_status for the current course/resource, processed counts and retry attempt, then reads the saved final summary. Repeated starts return the current task. Progress queries work while the browser is busy. If a chat disconnects, the task continues only while its MCP process stays alive; a terminated process is reported as interrupted on the next query. Completed results remain available after reconnecting. Task records are stored in _moodle/state/sync-jobs, separately from the file manifest. Only locks whose owning process has exited are recovered automatically; live locks are never expired by age.
Updating to 0.4.10: reconnect MCP after updating. sync_courses now returns a task instead of waiting for the final summary; integrations must poll get_sync_status. Daily sync defaults to quick. The CLI still waits for the final result; npm run sync -- --full explicitly checks old files. Independently installed skills are not replaced by program updates; review and update the supplied workflow if your old skill still selects full mode or expects a synchronous result.
The data root normally contains materials and _moodle. Course settings, sync state, classification rules and recognized legacy upgrade backups live in _moodle, which stays visible for recovery. Stop old MCP/CLI processes before upgrading, reconnect the new server, and read settings back.
Documentation
Testing and limitations — Chinese maintainer documentation
Release process — Chinese maintainer documentation
The server reads only selected courses that your account can access. It does not submit assignments, send messages, or modify school content. Authentication uses a dedicated browser profile; passwords and MFA codes are entered by the user. Keep login sessions, downloaded materials, and personal course configuration out of public repositories.
Style references
The following projects guide this project's documentation and presentation style:
Magenta CLI: distinct Installation and Update sections, prominent commands, and actionable upgrade guidance.
Levis: an English landing page with visible language switching, concise introductions, and consistent multilingual documentation.
Future documentation changes should follow these conventions: formal, concise wording; two primary entry points for installation and updates; and equivalent English and Chinese instructions. Commands and support claims must reflect this project's verified implementation.
License
MIT. The license covers this project's code, not university materials, branding, or third-party content.
Windows (experimental)
Use Node.js 24+ and Microsoft Edge, without WSL. Open scripts/setup.cmd or run the npm installation commands in PowerShell / CMD. Generate correctly escaped MCP paths with npm run codex-config. The same setup wizard offers skill installation; its paths and standalone command are described above.
Settings and the dedicated Edge profile live under %LOCALAPPDATA%/moodle-mcp, falling back to AppData/Local under the user directory. Materials default to Documents/MoodleSync. Paste the materials path from get_sync_settings into File Explorer. Windows permissions depend on the user directory ACL; POSIX mode flags do not provide equivalent macOS protection.
Automatic updating remains macOS-only. On Windows stop MCP and dedicated Edge, keep the old program directory, install/build in a new program directory, update the MCP entry, and recheck settings. Preserve configuration and materials.
The shared core and manifest schema remain unchanged. Real Windows installation, school login/MFA, file locking, long paths, ACL, and synchronization still require validation. Deep paths can encounter Windows path limits. macOS test results do not establish Windows support.
Windows uses a new dedicated edge-profile directory. Existing Windows Chrome profiles are preserved and are not imported; sign in again with Edge. Course settings and materials remain unchanged. If you explicitly set MOODLE_PROFILE_DIR, point it at a new dedicated Edge directory rather than the old Chrome profile. macOS retains its Chrome profile.
Available Tools
8 toolscheck_connectionBRead-onlyIdempotent
Check Moodle connection and dedicated login session; never return credentials.
Inputs: no named parameters.
confirm_setupAIdempotent
After explicit user confirmation of the displayed course list and current data root, persist setup approval. dataDir must match current settings. For a different root use npm run setup; this tool never migrates data.
Inputs: dataDir (required), confirmed (required).
download_resourceAIdempotent
Download a discovered file/folder module in an approved course to the approved materials directory. Keep old versions.
Inputs: courseId (required), moduleId (required).
get_sync_settingsBRead-onlyIdempotent
Show approved course IDs and local output directories without authentication data.
Inputs: no named parameters.
list_coursesBRead-onlyIdempotent
List enrolled My Modules courses including hidden courses. Only explicitly approved IDs may be synchronized.
Inputs: no named parameters.
list_resourcesBRead-onlyIdempotent
List visible resources for an approved course, with observed IDs, titles, types and available format metadata.
Inputs: courseId (required).
select_coursesAIdempotent
After user approval, replace the local course selection with observed My Modules IDs. Empty courseIds clears selection without deleting files. Local change only.
Inputs: courseIds (required).
sync_coursesAIdempotent
Perform one manual incremental sync for the locally approved courses. forceContentCheck bypasses ETag validation.
Inputs: forceContentCheck.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a fairly distinct action: connectivity check, course/resource discovery, single download, bulk sync, settings read, course selection, and setup confirmation. Minor overlap exists between sync_courses and download_resource (both fetch content) and between select_courses and confirm_setup (both touch setup state), but descriptions clarify the boundaries.
All eight tools follow a consistent snake_case verb_noun pattern (check_connection, list_courses, download_resource, sync_courses, select_courses, confirm_setup, etc.). No mixing of conventions or vague verbs.
Eight tools is well-scoped for a Moodle course-sync server, with each tool earning its place across connection, discovery, sync, and setup concerns. No redundant or trivial tools pad the set.
The surface covers connection, discovery, download, sync, settings, and setup lifecycle well. Minor gaps like cleanup of old versions or removing downloaded materials exist, but core workflows are covered.
Maintenance
Related MCP Connectors
PLATO (Pusan National University LMS) MCP server via Moodle Web Service API + ubboard scraping
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Absorb LMS MCP server for ChatGPT, Claude and any AI agent: list users, list course enrollments, list overdue learners, approve enrollment request, enroll users in a course, message learners, create user and deactivate user in your own Absorb LMS account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Absorb LMS yourself; Cotlet does not store your password and you need no Absorb LMS API key. About the official Absorb LMS API: Absorb LMS has an Integration API, a REST API with JSON for learners, courses, departments and grades, but it needs a private key tied to your portal that your Absorb account team provides, and your own code (checked 20 Oct 2026). Absorb's Aura MCP for Claude and ChatGPT is planned for 27 Oct 2026 and is read and answer only. Setup and FAQ: https://cotlet.dev/integrations/absorb-lms-api-mcp-server
LearnWorlds MCP server for ChatGPT, Claude and any AI agent: list users, list course learners, enroll users, unenroll users, update tags, send message, suspend user and grade assessment in your own LearnWorlds account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to LearnWorlds yourself; Cotlet does not store your password and you need no LearnWorlds API key. About the official LearnWorlds API: LearnWorlds has a REST API (v2) for courses, users, bundles, subscriptions, promotions, payments and certifications, but it comes with the Learning Center plan and higher, and you need your own code to use it (checked 5 Nov 2026). LearnWorlds has no official MCP server. Setup and FAQ: https://cotlet.dev/integrations/learnworlds-api-mcp-server
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables browser-based login to approved UTN Moodle sites and read-only access to the user's profile, course list, and course activities via local Chromium automation.2-
- AlicenseAqualityCmaintenanceEnables automated interaction with the Moodle platform, allowing users to list courses and modules, retrieve assignment details, and download course files via browser automation.6ISC
- AlicenseNot gradedqualityCmaintenanceEnables read-only Moodle access through MCP for querying courses, content, assignments, grades, forums, discussions, submissions, and calendar events, while supporting multiple profiles and local ICS export.58 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to browse your own university courses by downloading files, slides, announcements, deadlines, grades and lecture transcripts to your machine, then answering questions and searching across them through MCP tools. It logs in with your own account and refreshes only what changed.MIT