moodle-mcp-connector

An MCP server that connects AI agents to a Moodle site through Moodle's REST web services.

It exposes Moodle as typed tools an agent can call: list and search courses, read course structure, read the full text of Pages, Books, Labels and Lessons, look at quizzes, grades, deadlines and completion, and, when explicitly enabled, create and edit course content.

• Read-only by default. Write tools are only registered when MOODLE_ALLOW_WRITE=true.
• Content tool set. MOODLE_TOOLSET=content reduces the server to the tools needed to read and author course content.
• Token stays private. The token is read from the environment and is never logged or returned by any tool.

This project is not affiliated with, endorsed by, or supported by Moodle HQ or Moodle Pty Ltd. Moodle™ is a registered trademark of Moodle Pty Ltd.

It is based on the MIT-licensed moodle-mcp-bridge project (version 1.7.0); see LICENSE.

Requirements

• Python 3.11 or newer
• A Moodle site with web services enabled and the REST protocol turned on
• A web service token for a dedicated Moodle account (see Security)
• For the write tools that create and edit pages, books, labels, URLs, sections and activities: the companion Moodle plugin local_mcpconnector (repository: moodle-local_mcpconnector), release 0.1.0 (version 2026102123) or later, which has been tested on Moodle 5.3. server_info reports the installed plugin version and whether it is compatible. Read tools and the core-Moodle write tools (courses, users, enrolments, grading and so on) work without it.

Installation

This is release 0.2.0. Its plugin write tools need local_mcpconnector 0.1.0 (version 2026102123) or newer on the Moodle site; get it from moodle-local_mcpconnector.

Install it from PyPI with pip, ideally into a virtual environment:

pip install moodle-mcp-connector

Or run it without installing anything, with uv:

uvx moodle-mcp-connector

To stay on this release, pin it: pip install "moodle-mcp-connector==0.2.0" or uvx moodle-mcp-connector@0.2.0. To install straight from GitHub instead, use the release tag:

pip install "git+https://github.com/Teci-AI/moodle-mcp-connector.git@v0.2.0"

pip installs the moodle-mcp-connector command. Both of these start the server:

moodle-mcp-connector
python -m moodle_mcp_connector

The server talks MCP over stdio. Started by hand, it waits silently for an MCP client; that is expected. Stop it with Ctrl+C. To upgrade, run pip install --upgrade moodle-mcp-connector; uv picks up a new release with uvx moodle-mcp-connector@latest.

Configuration

All configuration comes from environment variables. The server also loads a .env file if one exists next to the package, in the repository root, or in the working directory; variables already set in the environment take precedence.

Example .env (already listed in .gitignore):

MOODLE_URL=https://moodle.example.edu
MOODLE_TOKEN=replace-me
MOODLE_ALLOW_WRITE=false
MOODLE_TOOLSET=content

Setting up Moodle

First, on any site:

1. Site administration → General → Advanced features: enable web services.
2. Site administration → Server → Web services → Manage protocols: enable REST.
3. Create a dedicated user for the agent (see Security). Give it only the roles it needs, in the courses it should work on, and make sure it has the webservice/rest:use capability.

Content tool set: use the plugin's ready-made service

The local_mcpconnector plugin ships a web service called MCP Connector Service (short name mcpconnector). It contains every local_mcpconnector_* function plus the 8 core read functions the content tool set uses, with file downloads allowed:

core_webservice_get_site_info
core_course_get_courses
core_course_get_courses_by_field
core_course_get_contents
core_enrol_get_users_courses
mod_quiz_get_quizzes_by_courses
mod_lesson_get_lessons_by_courses
mod_lesson_get_pages

It is disabled by default and limited to authorised users. To use it:

4. Install the plugin, downloaded from moodle-local_mcpconnector (Site administration → Plugins → Install plugins, or unpack it into local/mcpconnector) and complete the upgrade.
5. Site administration → Server → Web services → External services: edit MCP Connector Service, tick Enabled, and save.
6. On the same page, open Authorised users for that service and add the dedicated user.
7. Site administration → Server → Web services → Manage tokens: create a token for the dedicated user and MCP Connector Service. Put it in MOODLE_TOKEN, and set MOODLE_TOOLSET=content.

Other tools: use a custom service

The tools outside the content set (users, enrolments, grades, course creation, assignments, forums, messages and so on) call core functions that the ready-made service does not include. To use them, create your own service instead:

4. Site administration → Server → Web services → External services: add a custom service, add only the functions your tools need (see the tool tables), and authorise the dedicated user. If you also want the plugin's write tools, add the local_mcpconnector_* functions you need.
5. Tick Can download files on the service if you use read_activity or download_file.
6. Manage tokens: create a token for the dedicated user and that service.

A token belongs to exactly one service, so a token for the ready-made service can only reach the content tools, whatever MOODLE_TOOLSET says.

OpenCode configuration

Add the server to opencode.json (project) or ~/.config/opencode/opencode.json (global). {env:MOODLE_TOKEN} reads the token from your shell environment so it never lands in the config file:

With the command installed by pip:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "moodle": {
      "type": "local",
      "command": ["moodle-mcp-connector"],
      "enabled": true,
      "environment": {
        "MOODLE_URL": "https://moodle.example.edu",
        "MOODLE_TOKEN": "{env:MOODLE_TOKEN}",
        "MOODLE_TOOLSET": "content",
        "MOODLE_ALLOW_WRITE": "false"
      }
    }
  }
}

If moodle-mcp-connector is not on OpenCode's PATH (for example because it lives in a virtual environment), use the full path to the executable, such as ["C:/Users/you/moodle-mcp/.venv/Scripts/moodle-mcp-connector.exe"] or ["/home/you/moodle-mcp/.venv/bin/moodle-mcp-connector"].

Or let uv fetch and run it from PyPI, with nothing installed beforehand. The first start takes a little longer while uv downloads it; after that it runs from uv's cache. Use "moodle-mcp-connector@0.2.0" instead to pin this release:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "moodle": {
      "type": "local",
      "command": ["uvx", "moodle-mcp-connector"],
      "enabled": true,
      "environment": {
        "MOODLE_URL": "https://moodle.example.edu",
        "MOODLE_TOKEN": "{env:MOODLE_TOKEN}",
        "MOODLE_TOOLSET": "content",
        "MOODLE_ALLOW_WRITE": "false"
      }
    }
  }
}

Tools

The Content column marks the tools registered when MOODLE_TOOLSET=content. Write tools are only registered when MOODLE_ALLOW_WRITE=true, in either tool set.

Many read tools work on "the current user", meaning the user the token belongs to. They look up that user's id once with core_webservice_get_site_info and cache it. When an optional courseid/courseids argument is omitted, they use core_enrol_get_users_courses to find that user's courses.

Read tools

Write tools (MOODLE_ALLOW_WRITE=true)

Tools marked plugin need the companion plugin moodle-local_mcpconnector, which provides the local_mcpconnector_* functions.

Plugin version 2026102123 provides every function below. If the site runs an older plugin, or the token's service leaves a function out, the tool fails with a message naming the missing function rather than a raw Moodle error, and build_course checks every function an outline needs before it writes anything, rejecting the outline if any is missing.

Security

• Use a dedicated Moodle account for the agent, never a site administrator or your personal login. Give it only the roles it needs, and only in the courses it should touch.
• Give the web service the minimum functions. Add only the functions in the table above that your enabled tools actually call. A tool whose function is missing fails with a clear Moodle error; it cannot reach anything the service does not allow.
• Keep write mode off unless you need it. Without MOODLE_ALLOW_WRITE=true no write tool is registered at all. Combine write mode with MOODLE_TOOLSET=content to limit an authoring agent to course content.
• Never commit tokens. Keep MOODLE_TOKEN in your environment or in a .env file (ignored by git). In client configs, reference the environment (for example {env:MOODLE_TOKEN} in OpenCode) rather than pasting the token. If a token leaks, revoke it in Manage tokens and issue a new one.
• The token is sent as a POST field for web service calls. File downloads (read_activity, download_file) have to put it in the URL, so request URLs are kept out of logs and error messages, and both tools refuse any URL outside the MOODLE_URL site. An agent cannot get the token sent to another host.

Development

To work on the server itself, clone the repository and install it in editable mode with the development tools:

git clone git@github.com:Teci-AI/moodle-mcp-connector.git
cd moodle-mcp-connector
python -m venv .venv
# Windows:      .venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -e ".[dev]"
pytest

Contributing

See CONTRIBUTING.md for how to add a new tool, build the package and run the live integration tests.

License

MIT; see LICENSE.