moodle-ai-mcp

An AI-native MCP control plane for Moodle.

An MCP client (Claude Code, ChatGPT, Cursor, or anything else that speaks the Model Context Protocol) connects to this server and gets structured, accurate answers about a real Moodle site: what it is, who the connection is authenticated as, what it is allowed to do, which of Moodle's external functions it can reach, and — the part that makes it more than a REST wrapper — exactly which H5P libraries the site has installed and what their content schemas are.

This is not a thin wrapper around Moodle REST. The long-term goal is a control plane an AI client can use to design and build entire courses safely. This repository currently contains the first foundation of that.

Current maturity: foundation milestone, read-only

Working today:

• MCP server on stdio with seven curated tools, built on the official MCP TypeScript SDK

• A Moodle 5.2 local plugin (local_aimcp) with seven read-only external functions, real capability enforcement and PHPUnit coverage

• A capability-aware course read model: sections, activities, completion and grade configuration, reflecting what the authenticated identity may actually see rather than everything with a hidden flag attached

• Dynamic discovery of the external functions the authenticated service can reach, with lossless signature introspection

• Dynamic discovery of installed H5P libraries and their real installed semantics, converted to JSON Schema with explicit notes for everything JSON Schema cannot express

Not built, on purpose: any write operation, course/activity/H5P creation, the Course Blueprint engine, browser automation, file transfer, and hosting infrastructure. See "Limitations" below.

Related MCP server: Drupal Bridge MCP

Architecture

AI client  --MCP/stdio-->  apps/mcp-server (TypeScript, MIT)
                                 |
                                 |  authenticated Moodle web service call
                                 v
                           moodle/local/aimcp (Moodle plugin, GPL-3.0-or-later)
                                 |
                                 v
                           Moodle 5.2 core + H5P core

The server owns the protocol, the tool surface, orchestration and schema conversion. The plugin owns everything that only Moodle can answer: identity, context, capabilities, the external-function registry and the H5P engine. Moodle logic is never reimplemented in TypeScript, and orchestration never leaks into PHP.

Details, including why the tool surface is six tools rather than several hundred, are in docs/ARCHITECTURE.md.

Prerequisites

• Node.js 24

• Docker, with a Moodle 5.2 stack from moodle-docker

• A Moodle web service token for a user authorised on an enabled external service

Local development

Full instructions: docs/LOCAL-DEV.md. The short version:

cd ~/DEV/moodle-ai/moodle-ai-mcp

# 1. Start the Moodle stack (installs the persistence override, mounts the plugin)
./scripts/stack.sh start

# 2. Register the plugin with Moodle
docker exec -u www-data -w /var/www/html moodle-ai-webserver-1 \
  php admin/cli/upgrade.php --non-interactive

# 3. Attach the plugin's functions to your external service (idempotent)
docker exec -u www-data -w /var/www/html moodle-ai-webserver-1 \
  php public/local/aimcp/cli/provision_service.php --service=moodle_ai_mcp_dev

# 4. Build and run the server
npm install
npm run build
./scripts/run-server.sh

The database, moodledata and installed H5P libraries live in named Docker volumes, so ./scripts/stack.sh recreate is safe. Only ./scripts/stack.sh reset destroys data, and it asks first. Back up any time with ./scripts/backup.sh.

Credentials come from .env.local, which is a symlink to a file outside this repository. .env* is gitignored; see docs/SECURITY.md.

Connecting an MCP client

claude mcp add moodle-ai --scope local -- \
  /absolute/path/to/moodle-ai-mcp/scripts/run-server.sh

Or with the Inspector:

npx @modelcontextprotocol/inspector ./scripts/run-server.sh

Tools

Every tool is annotated readOnlyHint: true, destructiveHint: false, and returns both structuredContent and a JSON text fallback.

There is deliberately no generic "call any Moodle function" tool. Search and describe make the long tail discoverable; execution of arbitrary functions needs a safety classification that does not exist yet.

Tests

npm --prefix apps/mcp-server run typecheck      # TypeScript, strict
npm --prefix apps/mcp-server run test:unit      # pure logic, no Moodle needed
npm --prefix apps/mcp-server run build
npm --prefix apps/mcp-server run test:integration  # real Moodle + real MCP session

./scripts/lint-plugin.sh    # php -l over the plugin
./scripts/check-plugin.sh   # Moodle coding standard (moodle-cs)
./scripts/test-plugin.sh    # PHPUnit inside the Moodle container

The integration suite is not a mock: it spawns the built server as a child process, speaks MCP to it with the official SDK client, and asserts against the live site — including that the identity is the expected Moodle user and that no token appears in any output.

Limitations

• Read-only over MCP. No create, update, delete, enrol, grade, upload or download. The one thing in the repository that writes to Moodle is the development fixture CLI, which is not reachable from any MCP client or web service (see docs/SECURITY.md).

• No arbitrary function execution. Search and describe only.

• stdio only. HTTP transport is a future addition; the domain layer is already transport-free.

• No Course Blueprint, no diff/apply engine, no content generation.

• No browser automation, screenshots or accessibility auditing.

• moodle_course_inspect returns course structure, not learner performance: no grades and no per-user completion state.

• Moodle's front page is a course row but not a teaching course, so moodle_course_inspect rejects it. moodle_course_list still reports it, flagged isSiteCourse.

• H5P schema generation is one level deep: a nested library field fixes the wrapper shape and the allowed library versions, but its params follow that library's own semantics — fetch them with a second moodle_h5p_schema call.

• Some H5P and Moodle constructs cannot be expressed in JSON Schema (showWhen conditions, HTML tag whitelists, PCRE patterns, PARAM cleaning rules). They are preserved as x-h5p-* / x-moodle-* annotations and reported as conversion notes rather than dropped.

• Moodle REST cannot express an empty array or a true null; the client reports both as explicit warnings.

• The plugin is bind-mounted into the container from this repository; the rsync copy is kept only as a fallback. A host symlink does not work, for reasons explained in docs/LOCAL-DEV.md.

Licensing

• apps/mcp-server/ — MIT

• moodle/local/aimcp/ — GPL-3.0-or-later (required: it is a Moodle plugin)

No GPL implementation code is copied into the MIT server. Reference projects were studied as architecture references and reimplemented clean-room; the reasoning, per project, is in docs/REFERENCE-ARCHITECTURE.md.

Documentation

• docs/ARCHITECTURE.md — design and boundaries

• docs/REFERENCE-ARCHITECTURE.md — reuse matrix and licensing

• docs/LOCAL-DEV.md — reproducible local setup

• docs/SECURITY.md — secret handling, authorisation, surface constraints