Skip to main content
Glama

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

User 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 example mcp_8f3k2q9x

  • server.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_CONFIG or MOODLE_MCP_SERVER_CONFIG — choose the config file path

  • SERVER_ID — explicit server.id override

  • SERVER_NAME — explicit server.name override

  • SERVER_VERSION — explicit server.version override

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:3000

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

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 chains

Then 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 8080

Point the reference client at http://localhost:8080/v1.

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

list_courses

Full course catalog with category drill-down

get_course

Detail view for any course

list_course_users

Enrolled users with roles and access data (now supports course name search with interactive selection)

list_assignments

All assignments with due dates

list_categories

Full hierarchy with exact parent resolution

get_site_info

Instance overview — site name, version, course count

get_user

Detail view for a Moodle user

list_user_courses

Courses for a specific user

search_users

User search by standard Moodle identity fields

search_courses_by_name

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 API

Transport 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-server core for free, in any environment

  • ✅ Modify the source code for your needs

  • ✅ Build and distribute derivative works

You cannot:

  • ❌ Repackage the moodle-mcp-server core 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.

Available Tools

18 tools
get_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

    A3.9/5.0

    Scored across 18 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol (MCP) server that connects AI coding agents to your Moodle LMS. Fetch assignments, grades, deadlines, and sync everything to Obsidian automatically.
      -