Moodle Student MCP
This server lets your AI assistant read your own Moodle as a student—courses, assignments, deadlines, grades, forums and files—and manage your sign-in, without changing anything on Moodle.
Confirm who you are and that your token works (
whoami).List your enrolled courses (
list_courses).View a course's sections, topics and activities (
get_course_contents).Find assignments and their due dates across courses (
list_assignments).Check your submission status, grade and feedback for an assignment (
get_submission_status).See upcoming deadlines and pending work (
get_upcoming_deadlines).View your grades in a course (
get_grades).Read forums, including announcements (
list_forums,get_forum_discussions).List downloadable course files and download them locally (
list_files,download_files).Sign in, check auth status and log out (
login,auth_status,logout).
Provides tools for querying a Moodle site as a student, including courses, assignments, grades, forums, and files.
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 Student MCP What's due in the next two weeks?"
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.
Moodle Student MCP
An MCP server, packaged as a plugin for Claude Code, GitHub Copilot CLI, OpenAI Codex and Gemini CLI, that lets your AI assistant read your Moodle as a student. It uses Moodle's official mobile-app web service, so it only sees what you already see: courses, topics, assignments, deadlines, grades, forums and course files. No admin access needed, and nothing is ever changed on Moodle.
It works with any Moodle site that allows the official mobile app, and with any login method: a Moodle password, or SSO (Microsoft, Google, SAML, CAS) with MFA.
Requires Node.js 22+.
Two ways to use it
On your computer | In the cloud | |
Where the assistant runs | Claude Code, Claude Desktop, Copilot CLI, Codex, Gemini CLI, Cursor, ... on your machine | Claude Code on the web, CI, remote servers, containers |
Install | The plugin (or the MCP server) | A |
Sign in | A browser window opens; sign in as usual | Sign in once on your computer and pass the token as a secret |
Related MCP server: Moodle MCP for Students
Use it on your computer
1. Install
Pick your assistant. The plugin brings the MCP server plus the study and planning skills.
Assistant | Command |
Claude Code (plugin) |
|
Claude Code (server only) |
|
GitHub Copilot CLI |
|
OpenAI Codex |
|
Gemini CLI |
|
Any other MCP client (Claude Desktop, Cursor, VS Code, ...):
{
"mcpServers": {
"moodle-student": {
"command": "npx",
"args": ["-y", "@tcpassos/moodle-student-mcp"]
}
}
}If a client on native Windows cannot start
npx, use"command": "cmd", "args": ["/c", "npx", "-y", "@tcpassos/moodle-student-mcp"]. Claude Code runs plainnpxfine.
2. Sign in
Ask your assistant something like "connect to my Moodle" or "what's due this
week?". The first time, it asks for your Moodle address and calls the login
tool, which opens a browser window (Chrome, Edge, Brave, Chromium or Vivaldi,
whichever is installed; nothing is downloaded). Sign in as usual, SSO and MFA
included. The window closes and you're done.
Prefer the terminal? Run npx -y @tcpassos/moodle-student-mcp login.
Your Moodle password and token never pass through the chat. The token is kept
in your operating system's credential store (Windows Credential Manager, macOS
Keychain, Linux Secret Service), or in a private file (0600) where none is
available. It is never written into your project.
npx -y @tcpassos/moodle-student-mcp status shows who is signed in, and
logout removes the saved sign-in.
Use it in the cloud
Signing in needs a browser this program controls, because Moodle only hands
its token to the mobile app's moodlemobile:// links. So remote environments
are configured instead: you sign in once on your own computer and give the
environment the token as a secret.
1. Get the token on your computer
npx -y @tcpassos/moodle-student-mcp login
npx -y @tcpassos/moodle-student-mcp tokentoken copies two lines to the clipboard, MOODLE_URL=… and MOODLE_TOKEN=…,
without showing the token (--print shows it, in a terminal only).
Moodle tokens last 12 weeks by default (each site may change this). When the tools report an expired sign-in, run these two commands again and update the secret.
2a. Claude Code on the web
Cloud sessions don't load your local MCP servers or plugins; they load the
.mcp.json committed in the repository the session works on. One-time setup:
In that repository, commit this
.mcp.json. It also works on your computer: when the variables are not set they expand to nothing (:-), and the server uses your saved sign-in.{ "mcpServers": { "moodle-student": { "command": "npx", "args": ["-y", "@tcpassos/moodle-student-mcp"], "env": { "MOODLE_URL": "${MOODLE_URL:-}", "MOODLE_TOKEN": "${MOODLE_TOKEN:-}" } } } }At claude.ai/code, edit the environment you use:
Environment variables: paste the two lines from
token.Network access: choose Custom, add your Moodle host (e.g.
www.moodle.unisinos.br) and keep Also include default list of common package managers checked, sonpxcan download the server.
Start a new session and ask about your Moodle. New values reach a session when it is created.
To also get the skills there, copy the skills/ folders into the
repository's .claude/skills/. Environment variables are readable by anything
running in the session, Claude included, so keep the environment personal and
don't ask Claude to print them.
The environment's network secrets (Add secret) would keep the token out of
the session, but they can't carry it: they only add it to an HTTP header
(token or username and password), and Moodle reads the token only from the
request parameters (wstoken, token).
2b. Other cloud, CI and remote setups
Run the server with npx -y @tcpassos/moodle-student-mcp and set these
environment variables (as secrets); they take precedence over a saved sign-in:
Variables | When |
| Any account, including SSO |
| Accounts with a Moodle password (not SSO); the token is fetched and refreshed automatically |
If the environment restricts outbound traffic, allow your Moodle host (and the
npm registry, for npx).
Tools
Tool | What it does |
| Sign in through a browser window (explains the cloud setup where there is no screen) |
| Who is signed in, on which site, and where the credential comes from |
| Remove the saved sign-in |
| Your name, site, Moodle version and the time zone used for dates |
| Courses you are enrolled in |
| Sections/topics and activities of a course |
| Assignments with due dates |
| Whether you submitted, grade and feedback |
| Timeline of pending work |
| Your grades in a course |
| Forums, including the announcements forum |
| Recent posts in a forum |
| Downloadable files in a course |
| Download files and return their local paths |
Dates are ISO 8601 with an explicit offset (e.g. 2026-10-20T23:59:00-03:00),
in your Moodle profile's time zone.
Skills
Installed with the plugin (skills/, in the shared SKILL.md format):
moodle-setup: connect or fix the Moodle sign-in.
moodle-tasks: prioritized pending work for the week and a plan for the next deadline (also catches undated assignments and dates announced in the news forum).
moodle-materials: download a course's PDFs, slides and notebooks and analyze them.
moodle-grades: grades across courses, current standing, and what's needed to reach a target.
moodle-digest: a briefing of what's new and what's coming; pairs with scheduled runs.
moodle-study: a study guide (summary, flashcards, practice questions) from a topic's materials.
Configuration
All optional.
Variable | Default | Purpose |
| from the saved sign-in | Moodle address |
|
| Where |
| your Moodle profile zone | IANA zone for dates |
| auto-detected | Path to a Chromium-based browser for sign-in |
|
|
|
|
| Where the session and file store live |
On Windows the folder is outside AppData on purpose: Claude Desktop is a packaged (MSIX) app, and files its processes create under AppData go to a private copy that terminals and other assistants don't see.
Security and limits
Read-only, your data only. Every call goes through your own account's permissions.
download_filesonly fetches files listed in the course, so the token is never sent anywhere else.The token is a password. It never appears in tool results, logs or error messages.
tokencopies it to the clipboard and only prints it with--printin a real terminal. To revoke it: Moodle → Preferences → Security keys.How sign-in works. The server opens Moodle's mobile-app sign-in page (
admin/tool/mobile/launch.php) in a throwaway browser profile, reads the token from Moodle's answer over the DevTools protocol, checks that it is signed for this site and this attempt (md5(wwwroot + passport)) and closes the browser. Moodle only hands this token to its app'smoodlemobile://links, which no web page can receive, so signing in needs a browser this program controls: there is no "open a link on your phone" sign-in.Acceptable use. Automated access to your university's Moodle, even read-only, may fall under its IT policy. Keep request volumes modest. Admins can see token usage in the web service logs.
Troubleshooting
Problem | Likely cause |
"Not signed in" | Ask the assistant to sign in, or run |
Windows: signed in through Claude Desktop, but a terminal or another assistant says "Not signed in" | Versions before 0.2.1 kept the sign-in under AppData, where Claude Desktop's copy is private to it. 0.2.1 and later use |
"Found the saved Moodle sign-in … but could not read its token" | The session is saved, but its token is gone from the OS credential store (removed, or saved by another user account) or its token file is missing: sign in again. Where no credential store works, set |
"does not allow the Moodle mobile app service" | The site admin disabled mobile web services |
"This environment has no screen" | Cloud sandbox, SSH or container: see Use it in the cloud |
Browser window doesn't open | No Chromium-based browser found: install Chrome or Edge, or set |
Worked for weeks, now "expired" | Moodle tokens last 12 weeks by default: sign in again (and run |
"Moodle rejected the username/password" | The account uses SSO and has no Moodle password: use |
A tool returns an empty list | Not enrolled, or no data in that course |
Development
npm install
npm test # unit tests
npm run typecheck
npm run build
node --env-file=.env scripts/smoke.mjs # exercise every tool against a real MoodleInside this repository, run the CLI as node dist/cli.js <command>: here
npx @tcpassos/moodle-student-mcp resolves to the local folder (see below).
Release checklist: bump the version in package.json, .claude-plugin/plugin.json,
.claude-plugin/marketplace.json, plugin.json, gemini-extension.json and the
npx version range in the manifests, then npm publish --access public.
The plugin manifests start the server as
npx -y moodle-student-mcp@npm:@tcpassos/moodle-student-mcp@^x.y.z. Hosts
start plugin servers inside the plugin folder, whose package.json has the
same name, and a plain npx -y @tcpassos/moodle-student-mcp there resolves to
that unbuilt local copy instead of the published package.
License
Available Tools
11 toolsdownload_filesA
Download course files to ./materials// and return local paths.
Pass fileurls (from list_files) to download specific files, or omit it to
download every file in the course. The MCP client can then read the local
path of each result (e.g. open a PDF natively). Already-downloaded files
of the same size are reused (status "cached").
Inputs: course_id (required), fileurls.
get_course_contentsA
List the sections/topics and activities of a course.
Use the id from list_courses. For each section, returns its activities
(name, type, url, description and completion state when Moodle exposes it).
Inputs: course_id (required).
get_forum_discussionsA
List the recent discussions of a forum.
Use the forum_id from list_forums. Good for checking teacher
announcements. Returns title, author, date and the opening message.
Inputs: forum_id (required), limit.
get_gradesA
Show your grades in a course.
Use the id from list_courses. Returns each graded item with your grade,
the max, the percentage, the weight and feedback (only YOUR grades).
Inputs: course_id (required).
get_submission_statusA
Show the status of YOUR submission for an assignment.
Use the assign_id from list_assignments. Tells whether you submitted,
the submission state, whether it is still editable, whether it was graded,
the grade and the teacher's feedback. A status other than "submitted"
means it has not been turned in yet.
Inputs: assign_id (required).
get_upcoming_deadlinesA
List your upcoming tasks and deadlines (Moodle's "Timeline").
Aggregates assignment due dates, quiz closings, etc., sorted by date.
days is the look-ahead window (default 30). This is the best single
source for "what do I have to do and by when".
Inputs: days.
list_assignmentsA
List assignments with their due dates.
If course_ids is omitted, searches ALL your courses. Returns course,
assignment name, assign_id (for get_submission_status), due date, cutoff
date and max grade.
Inputs: course_ids.
list_coursesA
List the courses you are enrolled in.
For each: id (use it in the other tools), name, short name, progress (%) and last access date.
Inputs: no named parameters.
list_filesA
List the downloadable files of a course (PDFs, slides, notebooks, ...).
Use the id from list_courses. Returns, for each file: filename, mimetype,
size, the section/activity it belongs to, and the fileurl to pass to
download_files.
Inputs: course_id (required).
list_forumsA
List the forums in your courses (includes news/announcements).
If course_ids is omitted, scans all courses. Returns forum_id (for
get_forum_discussions), name, type and description.
Inputs: course_ids.
whoamiA
Confirm who you are on Moodle and that the token is valid.
Returns your name, user_id, site name, version and how many web service functions your token may call. Use it to diagnose the connection.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
All 11 tools have clearly distinct purposes: listing resources, fetching details, downloading files, and identity check. No two tools overlap in functionality.
Consistent verb_noun pattern: list_ for collections, get_ for single resource details, download_files for action, and whoami for identity. Mix of get_ and list_ is a sensible and predictable pattern.
11 tools is appropriate for a student-facing Moodle MCP. It covers the essential workflows (courses, assignments, forums, files, grades, deadlines) without being excessive.
The set covers reading and listing well but lacks tools for student actions such as submitting assignments or posting in forums. This is a notable gap for a student assistant tool.
Maintenance
Related MCP Connectors
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
PLATO (Pusan National University LMS) MCP server via Moodle Web Service API + ubboard scraping
Read-only access to a student's recorded classes: transcripts, notes, slides and concept map.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables Claude to interact with Moodle via the official REST API for read-only tasks like listing courses, materials, assignments, submissions, and grades. Uses token-based authentication and emphasizes safe, no-write operations.2MIT
- AlicenseAqualityBmaintenanceEnables AI apps to read a student's Moodle courses, upcoming and overdue due dates, assignment submission statuses, course grades, gradebook items and announcements. It is strictly read only, so it can never submit, edit or delete anything.17206 npmMIT
- AlicenseAqualityCmaintenanceEnables AI assistants to securely read course outlines, deadlines, announcements, forum discussions, and files from Moodle, track changes, and download or mirror course materials with a personal read-only token.101MIT
- AlicenseAqualityCmaintenanceProvides read-only access to a university's Moodle virtual campus, letting an AI assistant browse courses, sections and files, check upcoming deadlines, view assignment status and grades, and read forum announcements and threads. Authentication uses a Moodle token stored locally, with support for both undergraduate and postgraduate campus URLs.8MIT