Let’s get settled.
From your first terminal to your first course. Choose your machine, keep your usual university sign-in and let setup guide you.
01. A terminal to get started.
You’ll need Git, Python 3.11+ and macOS or Linux. On Windows, use WSL2 with a graphical display; this path has not been validated on the development machine.
git clone https://github.com/edouaz/moodle-mcp.git
cd moodle-mcp
bash setup.shThe script creates .venv, installs Python dependencies and Chromium, then opens the wizard. On Debian/Ubuntu, install python3-venv if creating the environment fails.
Already installed? Run python3 moodle.py setup to review your settings.
bash setup.sh --lang fr or python3 moodle.py --lang fr setup. Set MOODLE_MCP_LANG=fr for subsequent CLI commands. The language link in the navigation switches the website.02. Your university, your sign-in.
Enter your Moodle base URL, such as https://campus.example.edu/moodle. Keep an optional subdirectory, but leave out login or course paths.
Choose local, then open the browser from setup. Sign in normally with your university’s SSO and MFA. Once your course list is visible, confirm in the terminal. No university password is requested by the CLI.
python3 moodle.py doctor
python3 moodle.py session
python3 moodle.py coursesdoctor checks the MCP protocol without reading Moodle. The other commands use your saved session. To renew it, stop active requests and the tunnel, then run python3 moodle.py login.
Compatibility depends on your university’s Moodle theme. Empty results despite a valid session may require an adapter. Full local guide ↗
03. A conversation with your courses.
For a compatible OpenAI client, create a personal tunnel in OpenAI Platform and a runtime key in the same organization with the required permissions.
Setup can install the official client, asks for the tunnel_… ID and reads your key with hidden input. Choose whether to save it locally or enter it each time.
python3 moodle.py tunnel doctor
python3 moodle.py tunnel runThe tunnel stays in the foreground; Ctrl-C stops it. In your compatible OpenAI client, add an MCP connection of type Tunnel and select your tunnel. Availability depends on your account, workspace and permissions.
Ask your assistant to list your courses. A successful call confirms the complete connection; a local diagnostic alone does not.
.venv Python path as the command and the absolute mcp_server.py path as its argument. Configuration example ↗04. A little server, always there.
Ubuntu 24.04 or Debian 12+ with systemd are the documented starting points. Use a dedicated non-root account, persistent storage and enough memory for Chromium.
sudo apt update
sudo apt install git python3 python3-venv ca-certificates
git clone https://github.com/edouaz/moodle-mcp.git
cd moodle-mcp
bash setup.sh --vpsVPS setup installs Chromium’s system dependencies and may request sudo. You can save the runtime key in a private file for the background service.
Moodle sign-in needs a display.
On a headless server, setup defers sign-in. Use secure X11 forwarding (ssh -X, with an X server and xauth configured) or a remote desktop accessible only over SSH, then run python3 moodle.py login on the VPS. Cookies copied from another machine or IP may not be accepted.
Enable the service after signing in.
python3 moodle.py install-service
systemctl --user start moodle-tunnel
systemctl --user status moodle-tunnel
sudo loginctl enable-linger "$USER"The service uses your actual checkout paths and saved key. The last command enables startup at boot without an SSH session. To renew SSO: stop the service, sign in to Moodle, then restart it.
05. The everyday essentials.
python3 moodle.py courses
python3 moodle.py files --course 123 --limit 50
python3 moodle.py search --course 123 "Worksheet1"
python3 moodle.py download --course 123 \
--file-id "ID_FROM_THE_LISTING" --include-textReplace the IDs with values returned by the listings. Use next_offset as --offset to continue pagination. CLI downloads save one selected file on the machine running the command.
| MCP tools | What they do |
|---|---|
| Session and courses | Check the session and list your courses. |
| Files and search | List resources and search by name. |
| Download | Select a file and queue Mac delivery. |
| Mac folders and delivery status | Read the folder inventory and confirm receipt. |
Seven tools in total. Targeted downloads are limited to 20 MiB. PDF text is limited to 12,000 characters, without OCR. Full reference ↗
scraper.py without options downloads all courses. Use moodle.py for targeted operations.06. From the VPS to your Mac.
The optional Mac client fetches queued files over SSH and verifies their digest before acknowledging receipt. Set up an SSH key and make an initial connection to verify the server’s fingerprint.
# In the checkout installed on your Mac
.venv/bin/python sync_mac.py install \
--host student@vps.example.org \
--remote-path project/moodle-mcp/downloadsAdjust the host and server checkout path. The client runs every 30 seconds while the Mac is on. Files arrive in ~/Downloads/Moodle by default; MCP can also choose subfolders of Documents or Desktop.
queued means receipt is pending. Only delivered confirms the transfer. Mac client guide ↗
07. What stays. What gets shared.
University cookies stay in session.json on your machine. The URL is in .moodle/config.json. The profile and optional runtime key are in .tunnel/. All these files and your downloads are excluded from Git.
Tool results, including selected PDF text, are sent to your assistant. The full PDF does not automatically become a ChatGPT attachment. The Mac client publishes folder names to help choose a destination, never document contents.
Moodle names and content are untrusted data, never instructions. This website is static, with no analytics, forms or external resources. Security policy ↗
08. A little help.
My session expired.
Stop the tunnel or run systemctl --user stop moodle-tunnel. Run python3 moodle.py login with a display, complete SSO, check session and restart the tunnel.
The tunnel rejects the connection.
Check the key’s organization, tunnel ID and account permissions. Run python3 moodle.py tunnel doctor. Also check your workspace’s permissions for adding an MCP connection.
Chromium won’t start.
On Linux, install dependencies with .venv/bin/python -m playwright install --with-deps chromium. Interactive sign-in on a VPS requires a secure display.
The file hasn’t arrived on my Mac.
Check SSH, macOS folder permissions and .venv/bin/python sync_mac.py status. Files stay queued until receipt is confirmed by the client.
How do I update or uninstall?
Stop the tunnel, run git pull --ff-only, then rerun setup and the diagnostic. To uninstall, remove the service or LaunchAgent first and revoke the key. See the troubleshooting guide for all steps.