moodle-mcp-server
This server lets AI agents query a Moodle LMS via natural language over MCP, returning structured data without modifying the site.
Course discovery & details – List/filter full course catalog, search by name, view course details, and drill into categories.
User management queries – Search users by name/email/username/idnumber, fetch user profiles, list a user’s courses, and list course enrollees with roles across courses or categories.
Assignments – Get assignment lists with due dates, submission types, and grade scales.
Site overview – Retrieve LMS metadata, version, course count, and category hierarchy.
Cache management – Inspect, refresh, or clear course/category caches for data freshness.
User field schema administration – Discover/refresh/update/reorder standard and custom user fields for display/filtering.
Plugin extensibility – Optional reporting/analytics plugins (completion reports, recent activity, etc.) can auto-register tools.
Read-only, compliance-ready – Never modifies Moodle data; works over Moodle’s Web Services API with no LMS plugin.
Allows AI agents to query a Moodle LMS instance via its Web Services API, providing tools for course catalog, user enrollment, assignments, categories, site metadata, user lookup, and optional premium plugins for advanced reporting, user analytics, user directory, and compliance tracking.
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-mcp-server show me all courses in the current semester"
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-mcp-server — AI-Powered LMS Analytics
Ask your Moodle instance anything. Get structured answers in seconds.
moodle-mcp-server is an open-source MCP (Model Context Protocol) server that connects AI agents directly to Moodle's Web Services API. It is the first reference implementation of the Agentic Query Layer (AQL) pattern — a software design pattern for giving large language models safe, permission-aware, read-only access to structured data.
Instead of learning report builders, writing SQL, or exporting CSVs, you ask questions in plain English — the AI agent queries your LMS and returns structured data.
AQL pattern: https://csmediapro.com/notes/agentic-query-layer
Project home: https://csmediapro.com/products/moodle-mcp-server
npm package: https://www.npmjs.com/package/moodle-mcp-server-aql
MCP Registry: io.github.csmediapro/moodle-mcp-server-aql
Features
Core query tools — course catalog, user enrollment, assignments, category navigation, site metadata, user lookup, and cache management
Premium reporting plugins — optional tools such as course completion reports and recent activity can be attached through the plugin runtime
LLM-agnostic — works with Claude, GPT, Gemini, Ollama, or any MCP-compatible AI client
Zero LMS modification — uses Moodle's existing Web Services API, no plugin installation required
Compliance-ready data handling — secure, efficient data processing with privacy by design
Read-only — never modifies Moodle data, safe for production
Plugin-extensible — drop new tool modules into a directory; tools and optional agent routing hints auto-register at runtime
Related MCP server: Moodle MCP Server
Quick Start
Prerequisites
Node.js 20+
A Moodle instance with Web Services enabled
A Moodle API token (Site administration → Plugins → Web services → Manage tokens)
Use With An MCP Client
Most users launch the server through an MCP client such as Claude Desktop:
{
"mcpServers": {
"moodle-mcp-server-aql": {
"command": "npx",
"args": ["-y", "moodle-mcp-server-aql"],
"env": {
"MOODLE_URL": "https://your-moodle-instance.example",
"MOODLE_TOKEN": "your-moodle-web-services-token"
}
}
}
}Setup From Source
# Clone the repo
git clone https://github.com/csmediapro/moodle-mcp-server
cd moodle-mcp-server
# Install dependencies
npm install
# Configure
cp packages/server/.env.example packages/server/.env
# Edit .env: add your MOODLE_URL and MOODLE_TOKEN
# Run (stdio mode)
npm run server:build
node packages/server/dist/index.jsUser field schema
User field display settings are generated per Moodle instance and stored locally at
packages/server/data/user-field-schema.json. This file is intentionally ignored by git
because it can include site-specific custom profile fields.
After connecting to a Moodle site, run the refresh_user_field_schema tool once to
discover available standard and custom user fields. A minimal example shape is included
at packages/server/data/user-field-schema.example.json.
Separately installed plugins can use this schema to flatten custom profile fields
into stable keys such as school. The premium user-directory plugin, for example,
uses it to cache and summarize full-user directory fields outside the OSS core.
Config identity
The core owns two different server identity fields:
server.id— stable machine identity, for examplemcp_8f3k2q9xserver.name— human-facing display label
If server.id is missing, the core generates one once and persists it to the resolved config file before startup continues.
Environment overrides:
MOODLE_MCP_CONFIGorMOODLE_MCP_SERVER_CONFIG— choose the config file pathSERVER_ID— explicitserver.idoverrideSERVER_NAME— explicitserver.nameoverrideSERVER_VERSION— explicitserver.versionoverride
If server.id is missing and the resolved config path is not writable, startup fails deliberately.
Using the reference client
# From the project root
cp packages/client/.env.example packages/client/.env
npm run client:dev
# Open http://localhost:3000The client will auto-detect your Moodle instance and present a chat interface where you can ask questions in plain English.
Connecting an LLM
moodle-mcp-server needs an AI model to power the natural-language interface. You bring the model — the moodle-mcp-server core and reference client support any MCP-compatible provider.
Option 1: Run Locally (Recommended for Speed & Privacy)
Running a local model keeps all data on your own hardware — nothing leaves your network. Modern quantized models run well on consumer GPUs and even CPU-only setups.
Performance: A quantized 24B model on a single RTX 3090 delivers ~1.5-second responses after the first query — faster than most cloud APIs once the system is initialized.
Via Ollama (easiest)
# Install Ollama: https://ollama.com
ollama pull gemma3:12b # Fast, reliable tool use (~200ms TTFT)
ollama pull qwen3:14b # Strong reasoning, good for complex queries
ollama pull deepseek-r1:14b # Excellent at multi-step chainsThen point the reference client at http://localhost:11434 (Ollama's default).
Via llama.cpp (maximum control)
# Download a GGUF model (example: Devstral 24B Q4)
# Run the llama.cpp server:
llama-server -m devstral-24b-Q4_K_M.gguf --ctx-size 60000 --port 8080Point the reference client at http://localhost:8080/v1.
Recommended local models
Model | Size | Best For | Hardware |
Gemma 3 12B | ~7 GB VRAM | Fast tool calls, straightforward queries | Single consumer GPU |
Qwen 3 14B | ~8.5 GB VRAM | Complex reasoning, multi-tool chains | Single consumer GPU |
Devstral 24B Q4 | ~14.5 GB VRAM | Maximum capability, 60K context | RTX 3090 / 4090 |
Option 2: Cloud Providers
Anthropic (Claude):
export ANTHROPIC_API_KEY=sk-ant-...Select "Anthropic" in the reference client's provider dropdown. Claude Sonnet offers the most reliable tool-calling behavior.
OpenAI (GPT):
export OPENAI_API_KEY=sk-...Select "OpenAI" in the provider dropdown. GPT-4o performs well on structured queries.
Ollama Cloud:
Uses the same API as local Ollama, hosted at https://ollama.com/v1. Good middle ground — faster than local cold starts, more private than big cloud providers.
Option 3: Claude Desktop (Direct MCP)
Claude Desktop connects to the moodle-mcp-server core directly over stdio — no reference client needed.
Add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"moodle-mcp-server": {
"command": "node",
"args": ["/path/to/moodle-mcp-server/packages/server/dist/index.js"],
"env": {
"MOODLE_URL": "https://your-moodle-instance.com",
"MOODLE_TOKEN": "your-api-token"
}
}
}
}Restart Claude Desktop. The server's tools will appear in Claude's tool list — ask questions directly.
Tools
Core Tools (free, open source — AGPL)
Tool | Description |
| Full course catalog with category drill-down |
| Detail view for any course |
| Enrolled users with roles and access data (now supports course name search with interactive selection) |
| All assignments with due dates |
| Full hierarchy with exact parent resolution |
| Instance overview — site name, version, course count |
| Detail view for a Moodle user |
| Courses for a specific user |
| User search by standard Moodle identity fields |
| Search for courses by name with partial matching and interactive selection |
Premium Plugins (available separately)
Advanced Reporting — gradebooks, cross-course comparison, custom report builder
User Analytics — progress tracking, engagement scoring, risk flags
User Directory — cached directory listing and structured filtering across standard and custom profile fields
Compliance Pack — certification tracking, expiration alerts, audit exports
Architecture
This project is a reference implementation of the Agentic Query Layer (AQL) pattern — a layer that sits between an AI agent and your data, providing permission-aware, read-only, plain-language access without exposing the underlying data to the model.
User (plain English question)
│
▼
AI Agent (Claude / GPT / Gemini / Ollama / local)
│
▼ MCP Protocol
`moodle-mcp-server` ← AQL connector for Moodle
├── Tool Registry (core + plugins)
├── Agent Runtime Config (core + plugin rules)
├── Optimized Data Layer (secure, efficient data handling)
└── Moodle Client (REST API calls)
│
▼
Moodle Web Services APITransport modes
Stdio —
dist/index.js— runs as a subprocess, used by Claude Desktop and similar clients
The OSS core intentionally ships with stdio only. Any network-facing wrapper, remote supervision, or premium plugin attachment belongs in a separate commercial node agent or wrapper.
Plugin docs
License
AGPL v3 — see LICENSE.
This means you can:
✅ Use the
moodle-mcp-servercore for free, in any environment✅ Modify the source code for your needs
✅ Build and distribute derivative works
You cannot:
❌ Repackage the
moodle-mcp-servercore as a closed-source competing commercial product❌ Offer it as a network service without sharing your modifications
Trademark Notice
Moodle is a trademark of Moodle Pty Ltd. moodle-mcp-server is an independent CSMediaPro project and is not affiliated with, endorsed by, sponsored by, or officially connected to Moodle Pty Ltd or the Moodle project. The name is used descriptively to identify compatibility with Moodle LMS.
Built by CSMediaPro
moodle-mcp-server is built and maintained by CSMediaPro, a software development company specializing in AI integration, systems engineering, and workflow automation. It is the first reference implementation of the Agentic Query Layer (AQL) pattern.
AQL pattern: https://csmediapro.com/notes/agentic-query-layer
Contact: contact@csmediapro.com
Available Tools
18 toolsget_agent_runtime_configA
Internal client configuration tool. Returns declarative agent routing, prompt, rewrite, and continuation rules registered by core and loaded plugins.
Inputs: no named parameters.
get_cache_statusA
Inspect the Moodle course and category caches without changing them. Reports memory load state, disk cache validity, item counts, file size, TTL, timestamps, version, and Moodle site match. This tool never calls Moodle and never returns cached course or category records.
Inputs: target.
get_capabilitiesA
Show the effective registered tool catalog for this Moodle MCP server. Returns currently callable tools grouped by source: core tools and plugin tools. Table view shows Tool, Source, and Description.
Inputs: no named parameters.
get_courseA
Fetch structured details for a single Moodle course by ID. Returns full name, short name, summary, category, format, start/end dates, visibility, and completion tracking settings.
Inputs: courseid (required).
get_site_infoA
Returns information about the connected LMS instance: site name, version, release, authenticated user, available API functions, and total course count (from the pre-warmed cache). No parameters required — always returns cached data.
Inputs: no named parameters.
get_userA
Fetch one Moodle user by exact ID, email, or username. Provide exactly one of id, email, or username. Returns a single structured user record including any custom profile fields.
Inputs: id, _silo, email, username, +1 more.
get_user_field_schemaA
Admin/config tool: return the current user field schema for this Moodle instance. Shows every known user field (standard + custom), its type, source, and whether it is currently set to display in tables or accept filters. Use this when the user explicitly asks to inspect, configure, show, refresh, or troubleshoot the user field schema or table columns. Do not use this before ordinary requests to list or filter users; call list_users directly with filters instead. If no schema exists yet, the response will tell you to run refresh_user_field_schema. No parameters required.
Inputs: no named parameters.
list_assignmentsA
List all assignments in a Moodle course. Returns assignment ID, name, due date, allowed submission types, grade scale, and whether submissions are open. Does not return student submissions — use a separate tool for that.
Inputs: courseid (required).
list_categoriesA
List all LMS categories. Returns category ID, name, description, parent category, path, depth, and course count per category. Supports filtering by parent ID, exact parent name, and pagination. Use this to discover available categories, identify active vs inactive categories, and filter courses by category. Use the exact category ID when querying category-scoped tools.
Inputs: limit, offset, parent, parentid, +1 more.
list_coursesA
List LMS courses available to the configured API token. Returns course ID, full name, short name, category, category path, and visibility. Supports filtering and pagination via categoryid, categoryname, visible, limit, and offset. When categoryname is used, it must match an existing category name exactly; if multiple categories share that name, the tool will ask for the ID instead of guessing. Use visible=false for hidden courses and visible=true for visible courses. Use limit and offset for subset requests like first 10 or first 50. Do not request the full course list unless the user explicitly asks for all courses. Use this to discover available courses before drilling into details. Prefer exact category IDs from list_categories when available.
Inputs: limit, offset, visible, categoryid, +1 more.
list_course_usersA
List enrolled users in a specific Moodle course or across all courses in a specific LMS category. Provide exactly one of courseid, coursename, or categoryid. Returns user ID, full name, email, department, institution, last access timestamps, and enrollment roles. Category mode deduplicates overlapping users across courses before returning results. Use an exact category ID from list_categories when working at category scope.
Inputs: _silo, limit, offset, courseid, +2 more.
list_user_coursesA
List courses for a specific Moodle user ID. Requires an exact userid. Use get_user for exact email or username lookups first. Use search_users when a person is identified by name and multiple matches are possible. If multiple people match, ask the operator to choose the correct userid before calling this tool.
Inputs: userid (required), _silo, limit, offset.
manage_cacheB
Manage the Moodle course and category caches. Allows refreshing or clearing the in-memory and file-backed caches to ensure data freshness or free up memory. Use 'refresh' to update cache with latest data from Moodle, 'clear' to remove cached data, and 'all' to affect both courses and categories.
Inputs: action (required), target.
refresh_user_field_schemaA
Discover all available user fields from the connected Moodle instance and create or update the user field schema. Samples standard fields from the current user and custom profile fields from enrolled users across courses. Use this when: connecting to a new Moodle instance for the first time, or after a Moodle admin adds/removes custom profile fields, or when the operator asks to 'refresh the user fields'. Optional 'force' parameter (default false): when true, re-merges all fields from scratch (operator overrides on still-existing fields are preserved). When false, compares discovered fields against the stored schema and only updates if there are differences to report.
Inputs: force.
reorder_user_field_schemaA
Reorder displayed user table columns in the user field schema. Use this when the operator asks to move a column left, right, first, last, before another field, or after another field. The field and target values must be exact field keys from get_user_field_schema, such as id, fullname, email, lastaccess, department, institution, or suspended. Natural language examples: 'move last access all the way to the right' → {"field":"lastaccess","position":"end"}. 'move department after email' → {"field":"department","after":"email"}. 'put suspended before lastaccess' → {"field":"suspended","before":"lastaccess"}. 'move full name to the far left' → {"field":"fullname","position":"start"}.
Inputs: field (required), after, before, position.
search_courses_by_nameA
Search for courses by name, returning matching courses with their IDs and details. Useful for finding course IDs when you only know part of the course name. Supports partial matching on course full name, short name, and ID number. Case-insensitive search. Returns course ID, full name, short name, category, and visibility. Use this to find course IDs for other tools like list_course_users.
Inputs: searchTerm (required), limit.
search_usersA
Search Moodle users by firstname, lastname, email, username, or idnumber. Use this for direct person lookup, not structured directory filtering or reports. Provide at least one standard Moodle search field. Moodle performs the filtering first; this tool does not preload the full user directory. If a directory listing plugin is installed, prefer that plugin for filter-style requests. If multiple users match, do not guess downstream actions; select the correct user ID first.
Inputs: _silo, email, limit, offset, +4 more.
update_user_field_schemaA
Update display and filter settings for specific user fields. Only include fields you want to change — omitted fields keep their current settings. Use this when the operator wants to: show or hide a field in user search result tables (display), or enable/disable a field for schema-aware directory filtering (filterable). This is an admin/configuration tool, not a prerequisite for ordinary filtered user-list requests. FIELD KEYS: Use the exact short field keys from get_user_field_schema (common keys: id, fullname, email, username, department, institution, city, country, firstaccess, lastaccess, suspended, confirmed, idnumber). For a single field, prefer the shortcut fields: field='username', display=false. EXAMPLES: 'hide username from user tables' → {"field":"username","display":false}. 'hide firstaccess and department from user tables' → {"updates":{"firstaccess":{"display":false},"department":{"display":false}}}. 'make city visible in tables and available to schema-aware filters' → {"updates":{"city":{"display":true,"filterable":true}}}. 'show a discovered custom field in tables' → {"updates":{"customFieldKey":{"display":true}}}."
Inputs: field, display, updates, filterable.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have clearly distinct targets: search_courses_by_name vs list_courses, get_user vs search_users, and the four user_field_schema tools (get/refresh/update/reorder) are separable. Minor overlap exists where list_course_users and list_user_courses both span users and courses (opposite directions), and get_capabilities vs get_agent_runtime_config are both meta-tools that an agent could confuse.
All 18 tools use clean snake_case with a consistent verb_noun pattern (get_*, list_*, search_*, manage_*, refresh_*, update_*, reorder_*). The single deviation, search_courses_by_name, is still readable and follows the same convention family.
18 tools is slightly heavy for a read-oriented LMS client, with 4 tools devoted to user-field-schema administration and 2 to cache management. Each earns a place, but the schema-management cluster inflates the surface beyond the core browse/search workflow.
Course, user, and category discovery are well covered, but list_assignments explicitly delegates submissions to 'a separate tool' that does not exist, creating a dead end. Grade/submission retrieval and enrollment management are absent, leaving notable gaps for a full LMS surface.
Maintenance
Related MCP Connectors
An MCP server that integrates with Discord to provide AI-powered features.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that enables LLMs to interact with Moodle platforms to manage courses, students, assignments, and quizzes through natural language commands.710 npm45MIT
- AlicenseBqualityDmaintenanceAn MCP server that enables LLMs to interact with the Moodle platform to manage courses, students, assignments, and quizzes.7MIT
- AlicenseNot gradedqualityDmaintenanceA powerful Model Context Protocol (MCP) server that seamlessly integrates AI assistants with Moodle Learning Management System. Enable your AI assistant to access courses, retrieve educational content, download resources, and search through your learning materials.22 npm1MIT
- FlicenseNot gradedqualityBmaintenanceA Model Context Protocol (MCP) server that connects AI coding agents to your Moodle LMS. Fetch assignments, grades, deadlines, and sync everything to Obsidian automatically.-