moodle-mcp-bridge 1.7.0

🌐 Live site & guide · Quick start · Tools · How it works · Contributing · Releases

Table of contents

• What it does
• How it works (two pieces)
• Features
• Quick start
  • 1. Install the plugin
  • 2. Enable web services & get a token
  • 3. Run the MCP server
  • 4. Connect Claude Desktop
• Tool reference
• Testing from the shell
• Safety & write mode
• Extending it
• Contributing
• License

What it does

Moodle is the learning platform used by thousands of universities and schools. MCP-Moodle connects it to any Model Context Protocol client — Claude Desktop, Gemini CLI, ChatGPT desktop, Cursor, VS Code, and more — so an AI can:

• Read: list courses, inspect course contents, see enrolled students, quizzes, grades, quiz results, activity completion, notifications, and competencies.
• Build: create courses, users, categories, groups, enrolments, and actual content: pages, books, labels, URLs, forums, assignments, quizzes, and six quiz question types — or a whole course from one JSON outline with build_course.
• Protect: back any course up to a real .mbz file on your disk and restore it later.
• Safely: every write operation is off by default and only enabled with an explicit flag.

How it works (two pieces)

Moodle's built-in Web Services API can create courses and users, but it has no core function to create an activity (a Page, Book, Quiz…). So this project ships two parts that work together:

┌────────────────┐     MCP tools      ┌──────────────────┐    REST + token    ┌─────────────────┐
│  AI client     │ ◄────────────────► │   moodle-mcp     │ ◄────────────────► │   Moodle site   │
│ (Claude, etc.) │                    │  (Python server) │                    │  + local plugin │
└────────────────┘                    └──────────────────┘                    └─────────────────┘

Compatibility & authentication

Works with any Moodle 4.2 or newer: self-hosted or institutional. There is nothing site-specific in the code.

Authentication uses a web service token, not a password. The MCP server never sends a username or password, it sends a token (a long random string) that an admin generates in Moodle. The token is tied to one user account and one service (a fixed list of allowed functions), and it can only do what that user's capabilities permit.

Because the token is a separate auth channel, it works regardless of how your users log in: Manual, LDAP, SAML/SSO (Shibboleth, ADFS), Google/Microsoft OAuth, CAS, etc. all make no difference. A university Moodle behind SSO works exactly the same: an admin just creates a token.

What you need

Caveats (be honest with yourself here)

• You must be able to install a plugin: full control on self-hosted/institutional Moodle; a locked-down managed host may require the admin to do it.
• Some managed clouds (e.g. MoodleCloud free tier) block custom plugins and full web services, activity creation won't work there.
• Without the plugin, the MCP server's core tools (list/create courses, users, enrolment, grades) still work with a token; you only lose the plugin's activity-creation tools.

Features

• 88 tools: reads, a student-assistant layer (deadlines, dashboards, task analysis), core writes, activity creation, quiz results, completion tracking, backup/restore, and a one-call course builder
• Six quiz question types: multiple choice, true/false, short answer, essay, numerical (with tolerances), matching
• Read/write split: read tools always on; write tools gated behind MOODLE_ALLOW_WRITE=true
• Upgrade-safe plugin: uses Moodle's own add_moduleinfo(), never touches module tables directly
• Clean error handling: detects Moodle's JSON-error-on-HTTP-200 quirk and surfaces readable messages
• Token never logged: config from environment variables only
• One token for everything: read, core writes, and the plugin functions in a single service

Quick start

1. Install the plugin (local_mcpbridge)

Copy the local/mcpbridge/ folder into your Moodle so it lives at {moodle}/local/mcpbridge/, then visit Site administration as an admin, Moodle will detect it and prompt you to upgrade. Confirm, and you're done.

2. Enable web services & generate a token

In Moodle as an admin:

1. Enable web services: Site administration → Advanced features → tick Enable web services.
2. Enable REST: Server → Web services → Manage protocols → enable REST protocol.
3. Build the service: Server → Web services → External services. Use the ready-made MCP Bridge Service the plugin created, then click Functions and add the core read/write functions you want (list in Tool reference).
4. Authorise a user for the service and make sure they have the needed capabilities (notably moodle/course:manageactivities in the target courses).
5. Create a token: Server → Web services → Manage tokens → pick the user and the MCP Bridge Service. Copy it.

Verify before you wire up the AI: run the test script to confirm the plugin and token work end to end.

3. Run the MCP server

Easiest — from PyPI:

pip install moodle-mcp-bridge
MOODLE_URL=https://moodle.example.edu MOODLE_TOKEN=your_token moodle-mcp-bridge

Or from a checkout:

cd moodle-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # then edit .env with your URL + token
python server.py

4. Connect Claude Desktop

Add to claude_desktop_config.json (pip install):

{
  "mcpServers": {
    "moodle": {
      "command": "moodle-mcp-bridge",
      "env": {
        "MOODLE_URL": "https://moodle.example.edu",
        "MOODLE_TOKEN": "your_token_here",
        "MOODLE_ALLOW_WRITE": "true"
      }
    }
  }
}

Running from a checkout instead? Use "command": "/absolute/path/to/moodle-mcp/.venv/bin/python" with "args": ["/absolute/path/to/moodle-mcp/server.py"].

Not just Claude: any MCP client works

MCP is an open protocol, so the same server works with Gemini CLI, ChatGPT desktop (developer mode), Cursor, Windsurf, VS Code Copilot agent mode, Cline, LM Studio, and anything else that speaks MCP. The config is nearly identical everywhere — the moodle-mcp-bridge command plus the three env vars. Example for Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "moodle": {
      "command": "moodle-mcp-bridge",
      "env": {
        "MOODLE_URL": "https://moodle.example.edu",
        "MOODLE_TOKEN": "your_token_here",
        "MOODLE_ALLOW_WRITE": "true"
      }
    }
  }
}

Tool-use quality depends on the model: with 88 tools, stronger models chain calls (create course → add section → add quiz) more reliably than small local ones.

Restart Claude Desktop and the Moodle tools appear.

Tool reference

88 tools, grouped by what they touch. Access shows whether a tool is always available (read) or needs MOODLE_ALLOW_WRITE=true (write). Tools backed by the plugin are marked plugin; everything else uses Moodle core functions.

Courses & structure

Course builder & backup

Content & activities

Quizzes & questions

Users, enrolment & groups

Communication

Assignments & grading

Grades, progress & completion

Planning & insights

Search & assist

Quizzes: the six add_*_question tools use Moodle's Question Bank API (multiple choice, true/false, short answer, essay, numerical, matching). That API is version-sensitive — tested on Moodle 5.0; test on your version first.

Missing function? A tool whose web service function isn't in the token's service returns a clean "access control exception" — add the function to MCP Bridge Service and retry. Installing plugin 1.6.0+ registers the complete list automatically.

Testing from the shell

Confirm the plugin + token work before wiring up the AI:

cd moodle-mcp

# Read-only checks (site info + course list):
MOODLE_URL=https://moodle.example.edu MOODLE_TOKEN=xxxx ./test_rest.sh

# Full write test, creates a page, label, url, book, quiz + question in COURSEID:
MOODLE_URL=https://moodle.example.edu MOODLE_TOKEN=xxxx COURSEID=2 ./test_rest.sh --write

A successful create returns e.g. {"cmid": 47, "instanceid": 12}. A Moodle error (still HTTP 200) returns a JSON object with an exception field, which the server surfaces as a clean message.

Safety & write mode

For a full hardening checklist (dedicated service account, scoped role, HTTPS, token expiry), see SECURITY.md.

• Writes hit live data. Every write tool creates or changes real records. There is no dry-run.
• Writes are gated. If MOODLE_ALLOW_WRITE is not exactly true, the server registers read tools only: writes cannot be exposed by accident.
• The token is the blast radius. Bind it to a dedicated service account with only the capabilities and courses you need. A site-admin token lets the AI do anything an admin can.
• The token is never logged: read from the environment, sent only to Moodle over HTTPS.
• Start read-only. Turn on write mode deliberately, on a test course, and confirm the shell test passes first.

Extending it

Adding a new capability (e.g. create_assignment, create_forum) is copy-paste-modify. Each plugin function follows the same three-method shape, see create_page.php as the template, and CONTRIBUTING.md for the full recipe.

Contributing

Contributions are very welcome, this is built to be extended!

1. Fork the repo (top-right Fork button).
2. Create a branch: git checkout -b feature/my-thing.
3. Make your change and test it (php -l, py_compile, ideally against a real Moodle).
4. Push and open a Pull Request to main.

See CONTRIBUTING.md for the full workflow, coding standards, and the pattern for adding a new function. Please also read our Code of Conduct. Found a bug or want a feature? Open an issue.

License

MIT, free to use, modify, and distribute.