moodle-mcp

Model Context Protocol server for Moodle development. Plug into Claude Desktop, Cursor, Continue, Cline, or any MCP-capable assistant — get live moodledev.io documentation lookups right in your editor.

Companion to claude-moodle-dev — that plugin teaches AI assistants the Moodle conventions; this server gives them live access to the canonical docs.

What you get

Ten MCP tools, hardened to survive site redesigns:

| Tool | Purpose | |------|---------| | search_moodle_docs(query, limit=5, offset=0, version?) | Search moodledev.io. Synonym expansion, quoted-phrase boost, BM25 + trigram-cosine rerank, pagination, optional version filter (4.4, 4.5, …). Optional Algolia DocSearch fast-path. | | fetch_moodle_page(url) | Pull a single page in full — body text + headings. Rejects off-host URLs, non-http schemes, and path traversal. | | get_hooks_api_listeners() | Surface the core Hooks API index + detected hook classes. | | get_capability_docs(component?) | Access API lookup with a RISK_* quick-reference card; optional component scope. | | lookup_db_xmldb(query) | Focused XMLDB / database schema search. | | list_plugin_types() | Table of every Moodle plugin type with one-line hints + docs URL. | | get_version_info() | Current Moodle versions parsed from /general/releases. | | search_tracker(query, limit=5, affects_version?, fix_version?) | Issue search against tracker.moodle.org (Jira), now with version filters. | | list_ws_functions() | List Moodle Web Services functions available to the configured instance token. Requires MOODLE_URL + MOODLE_TOKEN. | | call_ws_function(function, args) | Invoke a Moodle WS function against a real instance. SSRF-guarded, function-name allowlisted, refuses private/loopback hosts unless explicitly overridden. |

Plus MCP resources (moodle://docs/apis/... for one-click page reads), prompts (moodle-plugin-skeleton, moodle-capability-review, moodle-hooks-migration, explain-capability, find-endpoint, explain-plugin-type, xmldb-upgrade, diagnose-mdl), tool annotations (readOnlyHint, destructiveHint) for client safety, and progress notifications during multi-fetch searches.

No API keys required for docs. Pulls the public sitemap, caches it on disk (~/.cache/moodle-mcp/), scores against your query, fetches top pages concurrently with retry + conditional GET + Retry-After header respect.

Optional environment variables

| Variable | Purpose | |----------|---------| | MOODLE_URL | Base URL of a real Moodle instance (https). Enables WS tools. | | MOODLE_TOKEN | WS token for that instance. | | MOODLE_WS_ALLOW_INSECURE | Set to 1 to permit http:// or private/loopback hosts (local dev only). | | MOODLE_DOCS_ALGOLIA_APP_ID | Algolia DocSearch app ID. Enables higher-precision recall over sitemap BM25. | | MOODLE_DOCS_ALGOLIA_API_KEY | Algolia public search key. | | MOODLE_DOCS_ALGOLIA_INDEX | Index name (default: moodledev). |

CLI

moodle-mcp --version
moodle-mcp --check        # diagnostic: fetch sitemap + sample page, exit
moodle-mcp --log-level DEBUG

Docker

docker build -t moodle-mcp .
docker run --rm -i moodle-mcp

Install

From PyPI (once published)

pipx install moodle-mcp

From source

git clone https://github.com/SaadRahman01/moodle-mcp
cd moodle-mcp
pipx install .

Wire it up to your assistant

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "moodle": {
      "command": "moodle-mcp"
    }
  }
}

Restart Claude Desktop. Ask: "Search the Moodle docs for how to add a capability."

Claude Code

claude mcp add moodle moodle-mcp

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "moodle": { "command": "moodle-mcp" }
  }
}

Continue.dev

~/.continue/config.yaml:

mcpServers:
  - name: moodle
    command: moodle-mcp

Cline / Windsurf / any MCP client

Spawn moodle-mcp as a stdio MCP server. No extra arguments required.

How it works

   query
     │
     ▼
┌─────────────────────────────────────────┐
│  fetch sitemap.xml  (cached per session)│
└─────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────┐
│  score URLs by slug-token overlap       │
└─────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────┐
│  fetch top N pages → extract main text  │
└─────────────────────────────────────────┘
     │
     ▼
   markdown bundle (title, URL, excerpt)

No external search index. No API key. The only network dependency is https://moodledev.io being reachable.

Roadmap

• lookup_capability(name) — resolve capability → metadata + risk bitmask
• lookup_hook(name) — Hooks API 4.4+ listener signatures
• validate_version_php(path) — local lint
• lookup_db_field(table, column) — XMLDB metadata
• Algolia DocSearch fast-path (when available)

Vote / request: open an issue.

Development

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .

Contributing

PRs welcome. Add a new tool by:

1. Implementing the backend in src/moodle_mcp/<your_module>.py.
2. Registering the tool in src/moodle_mcp/server.py.
3. Adding tests in tests/.

License

MIT.

Credits

Built by Saad Rahman. Companion of claude-moodle-dev. Powered by the Model Context Protocol and the Moodle Developer Documentation.