Skip to main content
Glama

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

  1. Download the ZIP attachment with the highest version number from Releases, then extract it to a permanent program directory.

  2. On macOS open scripts/setup.command; on Windows open scripts/setup.cmd (experimental). The launcher checks prerequisites, installs dependencies with your confirmation, builds the server, and starts setup.

  3. 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.

  4. 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 build

Have 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 update

The 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-config

Add 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

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 tools
check_connectionB
Read-onlyIdempotent

Check Moodle connection and dedicated login session; never return credentials.

Inputs: no named parameters.

confirm_setupA
Idempotent

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_resourceA
Idempotent

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_settingsB
Read-onlyIdempotent

Show approved course IDs and local output directories without authentication data.

Inputs: no named parameters.

list_coursesB
Read-onlyIdempotent

List enrolled My Modules courses including hidden courses. Only explicitly approved IDs may be synchronized.

Inputs: no named parameters.

list_resourcesB
Read-onlyIdempotent

List visible resources for an approved course, with observed IDs, titles, types and available format metadata.

Inputs: courseId (required).

select_coursesA
Idempotent

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_coursesA
Idempotent

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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers