# Moodler Mcp > Moodle LMS MCP server: talk to your Moodle in plain English - **Type:** MCP server - **Install:** `agentstack add mcp-ghaithalhallak8-moodler-mcp` - **Verified:** Pending review - **Seller:** [GhaithAlHallak8](https://agentstack.voostack.com/s/ghaithalhallak8) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [GhaithAlHallak8](https://github.com/GhaithAlHallak8) - **Source:** https://github.com/GhaithAlHallak8/moodler-mcp ## Install ```sh agentstack add mcp-ghaithalhallak8-moodler-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Talk to your Moodle in plain English. --- **moodler-mcp** is an open-source MCP server that plugs your Moodle account into [Claude Desktop](https://claude.ai/download) (or any MCP-compatible AI assistant). Once installed, you can stop wrestling with Moodle's UI and just ask questions in natural language. Built in Python, [MIT](LICENSE) licensed, distributed as a one-click `.mcpb` bundle. ## What you can do with it A few real queries it handles: - _"What's due this week?"_ → pulls from your calendar and assignment list - _"What do I need to do for my THI212 project?"_ → reads the assignment page and returns the full spec - _"Why are my grades in INT201 low?"_ → scrapes your user grade report and summarises what's posted - _"Download the week 4 lecture slides and summarise them."_ → fetches the PDF through Moodle's resource redirect chain and reads it directly (PDFs and all) It handles courses, assignments, deadlines, grades, feedback, file downloads, and — for staff accounts — assignment participant lookups and student search. The full tool list is [below](#tools). ## Disclaimer **moodler-mcp is an unofficial, independent project. It is not affiliated with, endorsed by, or sponsored by Moodle Pty Ltd or any educational institution.** ### Intended use This tool is built to help students and instructors interact with their own Moodle account more efficiently — checking deadlines, reviewing course materials, tracking grades, and organizing coursework through an AI assistant. ### Not intended for - **Academic dishonesty of any kind.** This includes using an LLM to generate answers for quizzes, assignments, or exams accessed through this tool, submitting AI-generated work as your own, or any activity that violates your institution's academic integrity policy. The tool exposes your coursework to an AI — what you do with that access is your responsibility, and misuse can have serious consequences (failing grades, suspension, expulsion). - **Any use that violates your institution's Moodle terms of service.** ## Install ### Prerequisites Both install paths need [`uv`](https://docs.astral.sh/uv/) on your machine — it'll fetch Python 3.14 for you on first run. ```bash # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh ``` ```powershell # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ### Option 1: One-click bundle (recommended) 1. Grab `moodler-mcp.mcpb` from the [latest release](https://github.com/GhaithAlHallak8/moodler-mcp/releases). 2. Double-click the file (or drag it into Claude Desktop's extensions view). 3. When prompted, enter the base URL of your Moodle instance (e.g. `https://mylms.example.edu`, no trailing slash). 4. Start a new conversation. The first time you ask anything Moodle-related, a Chromium window will open so you can complete single sign-on — that's a one-time step. That's it. Your session stays cached locally until it expires. ### Option 2: From source ```bash git clone https://github.com/GhaithAlHallak8/moodler-mcp.git cd moodler-mcp uv sync export MOODLE_URL=https://mylms.example.edu uv run python -m moodler_mcp ``` To wire it into Claude Desktop manually, add to `claude_desktop_config.json`: ```json { "mcpServers": { "moodler-mcp": { "command": "uv", "args": ["--directory", "/absolute/path/to/moodler-mcp", "run", "python", "-m", "moodler_mcp"], "env": { "MOODLE_URL": "https://mylms.example.edu" } } } } ``` ## How authentication actually works > **No API tokens. No institutional paperwork. No `MOODLE_API_TOKEN`.** moodler-mcp does **not** use Moodle's public Web Services REST API. Instead, it drives a real browser session — the same way you log in from your laptop: 1. On first run, it launches a headless Chromium via [Playwright](https://playwright.dev/python/) and navigates to `${MOODLE_URL}/my/`. 2. If it can't find a valid session, it re-opens the browser in **headed mode** so you can complete your institution's SSO flow (SAML, Azure AD, whatever your IdP is). 3. Once you're logged in, it extracts the `MoodleSession` cookie and scrapes the `sesskey` from the dashboard HTML, then saves both to `~/.moodler-mcp/browser_state.json`. 4. Subsequent calls reuse that session headlessly, authenticating against Moodle's internal AJAX endpoint (`/lib/ajax/service.php`) — the same endpoint the Moodle web UI uses. 5. If the session expires (the Moodle returns `servicerequireslogin` or redirects to `/login/`), the cookie is cleared and the flow re-runs once. This means two things: - **It works anywhere your student account works.** If you can log into Moodle in a browser, moodler-mcp can too. No permissions to request, no admin to email. - **It fails gracefully.** Session drift is automatically recovered on the next call. ## Configuration | Variable | Required | Default | Description | | ------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------- | | `MOODLE_URL` | ✅ | _(none)_ | Base URL of your Moodle instance, no trailing slash. Example: `https://mylms.example.edu` | | `MOODLER_CACHE_DISABLED` | ❌ | _unset_ | Set to `1` to disable the local SQLite cache. | ## Where state lives All local state is under `~/.moodler-mcp/`: - `browser_state.json` — Playwright storage state (your cached Moodle session cookie). - `cache.db` — SQLite cache of Moodle API responses. See [caching](#caching). - `downloads/` — files fetched by `download_resource`. Exposed back to the MCP client as `downloads:///{filename}` resources. Delete the directory to wipe everything. ## Caching Moodle reads go through a small SQLite-backed cache so repeated tool calls return instantly. TTLs are per-operation: | Data | TTL | | ------------------------ | ------ | | Enrolled course list | 1 day | | Course sections | 1 hour | | Calendar / deadlines | 30 min | | Assignment participants | 10 min | | Assignment view / status | 10 min | | Course module metadata | 1 day | | Grade report HTML | 5 min | | Student search | 15 min | Disable with `MOODLER_CACHE_DISABLED=1`, or call the `clear_cache` tool to wipe all or part of the cache (`clear_cache(pattern="get_grade_report_html")` to target a subset). Broken cache reads never fail a tool call — corruption or disk errors are logged and treated as a cache miss. ## Tools | Tool | For | Description | | ----------------------------------- | ----------- | ----------------------------------------------------------------- | | `list_courses` | Students | List your enrolled Moodle courses. | | `get_course_contents` | Students | Get all sections, activities, and resources in a course. | | `get_module_content` | Students | Read any Moodle module page (assignment, folder, URL, page). | | `download_resource` | Students | Download a Moodle file (PDF, DOCX, PPTX…) and return its content. | | `read_downloaded_file` | Students | Re-read a previously downloaded file from the local cache. | | `get_course_deadlines` | Students | List all assignments, quizzes, and deadlines for a course. | | `get_upcoming_deadlines` | Students | Upcoming deadlines across all courses, sorted by date. | | `get_assignment_feedback` | Students | Your submission status, grade, and feedback for an assignment. | | `get_course_grades` | Students | Scrape your user grade report for a specific course. | | `get_assignment_participants` | Instructors | List students submitting to an assignment, with status. | | `get_assignment_participant_detail` | Instructors | Detailed submission info for one student on one assignment. | | `search_students` | Instructors | Search students enrolled in a course by name. | | `clear_cache` | All | Clear the local SQLite cache, optionally matching a substring. | ### For instructors (experimental) The teacher-facing tools (`get_assignment_participants`, `get_assignment_participant_detail`, `search_students`) work but have had significantly less real-world testing than the student-facing flows. Expect rough edges and please [open an issue](https://github.com/GhaithAlHallak8/moodler-mcp/issues) if something breaks — traceback + the AJAX method that failed is enough. ## Privacy moodler-mcp runs entirely on your machine. It connects only to your Moodle instance and to your AI assistant. No telemetry, no analytics, no outbound connections to any third party. Your Moodle session cookie is stored locally in `~/.moodler-mcp/browser_state.json` and nowhere else. See [PRIVACY.md](PRIVACY.md) for the full statement. ## Contributing PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the fork-and-PR workflow, local setup (`uv sync` + `pre-commit`), and conventional-commit PR title rules (release-please reads them to cut releases). ## License [MIT](LICENSE) © Ghaith AlHallak ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [GhaithAlHallak8](https://github.com/GhaithAlHallak8) - **Source:** [GhaithAlHallak8/moodler-mcp](https://github.com/GhaithAlHallak8/moodler-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ghaithalhallak8-moodler-mcp - Seller: https://agentstack.voostack.com/s/ghaithalhallak8 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.