Moodle Aql MCP server

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 Moodle connector behind CSMediaPro's broader Agentic Query Layer (AQL) work.

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.

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

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

• MOODLEMCPCONFIG or MOODLEMCPSERVER_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

Shortened. The full README is on GitHub.