moodle-mcp

A Model Context Protocol (MCP) server that connects AI coding agents — Hermes, Claude Code, and OpenCode — to your Moodle LMS. Fetch assignments, grades, deadlines, and sync everything to Obsidian automatically.

✨ Features

📚 Courses & Content

📝 Assignments & Deadlines

📊 Grades & Progress

📅 Calendar & Events

🗂️ Aggregated Overviews

🗒️ Obsidian Sync

🔄 Semester Auto-Archive

When sync_moodle_to_obsidian detects that your Moodle courses have changed significantly (i.e., you moved to a new semester), it automatically archives the previous semester's notes before overwriting:

Obsidian Vault/Academic/
  Moodle/                       ← always up-to-date (current semester)
    .semester_courses.json      ← state file (hidden, tracks course IDs)
    Dashboard.md
    Deadlines.md
    Grades.md
    Courses/
  Archive/
    Semester-2026-07/           ← auto-created on semester rollover
      Dashboard.md              ← snapshot of old semester
      Courses/                  ← all old course notes preserved
      Grades.md
      Archive-README.md         ← log of what changed and when

Trigger logic: archive fires when >50% of known course IDs are replaced (or all are new). Minor changes (e.g., 1 course dropped/added) are ignored.

🚀 Quick Install

A single install script handles all supported CLI agents automatically:

curl -fsSL https://raw.githubusercontent.com/doomscrollsurvivor/moodle-mcp/main/scripts/install-mcp.sh | bash

Or clone first and run locally:

git clone https://github.com/doomscrollsurvivor/moodle-mcp.git
cd moodle-mcp
bash scripts/install-mcp.sh

The script detects which agents are installed and configures each one. See scripts/install-mcp.sh for full details.

⚙️ Manual Setup

1. Prerequisites

• Python ≥ 3.10

• uv (recommended) or pip

• A Moodle account with Web Services enabled

2. Get Your Moodle Token

1. Go to https://<your-moodle-url>/user/managetoken.php

2. Find the row with Moodle mobile web service in the Service column

3. Copy the token

3. Create .env

cp .env.example .env

Edit .env:

MOODLE_URL=https://your-moodle-url.example.com/webservice/rest/server.php
MOODLE_TOKEN=your_token_here

# Optional — filter assignments to your own class (Polibatam multi-class fix)
MOODLE_MY_CLASS=Pagi C

# Optional — custom Obsidian vault path
OBSIDIAN_VAULT_PATH=/home/yourname/Obsidian Vault

4. Install the Package

# With uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

5. Configure Your Agent

Jump to the section for your agent:

• Hermes Agent

• Claude Code

• OpenCode

• Claude Desktop / Cursor (GUI)

🤖 Hermes Agent

Hermes uses a local Python launcher script for MCP. This is the recommended setup for the akademik profile.

Auto-configure (recommended)

bash scripts/install-mcp.sh --agent hermes --profile akademik

Manual configure

1. Copy the launcher:

mkdir -p ~/.hermes/scripts
cp scripts/moodle_mcp_local_launch.py ~/.hermes/scripts/

2. Add to ~/.hermes/profiles/akademik/config.yaml (or ~/.hermes/config.yaml for default):

mcpServers:
  moodle:
    command: python3
    args:
      - /home/<you>/.hermes/scripts/moodle_mcp_local_launch.py
    env:
      MOODLE_URL: "https://your-moodle-url/webservice/rest/server.php"
      MOODLE_TOKEN: "your_token_here"
      MOODLE_MY_CLASS: "Pagi C"
      OBSIDIAN_VAULT_PATH: "/home/<you>/Obsidian Vault"

3. Verify:

hermes --profile akademik mcp test moodle

Expected output: ✓ Connected ✓ Tools discovered: 40

🤖 Claude Code

Claude Code reads MCP config from .claude/settings.json (project-level) or ~/.claude/settings.json (global).

Auto-configure

bash scripts/install-mcp.sh --agent claude-code

Manual configure — Global

claude mcp add -s user moodle-mcp -- python3 /path/to/moodle-mcp/src/moodle_mcp/server.py

Then set env vars by editing ~/.claude.json (or use the script).

Manual configure — JSON

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "moodle-mcp": {
      "command": "uvx",
      "args": ["moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle-url/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here",
        "MOODLE_MY_CLASS": "Pagi C",
        "OBSIDIAN_VAULT_PATH": "/home/<you>/Obsidian Vault"
      }
    }
  }
}

Or to use local source (no PyPI needed):

{
  "mcpServers": {
    "moodle-mcp": {
      "command": "python3",
      "args": ["/path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py"],
      "env": {
        "MOODLE_URL": "https://your-moodle-url/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

Verify

claude mcp list

In a Claude Code session: ask "list my Moodle courses" — it should call get_my_courses.

🤖 OpenCode

OpenCode reads MCP config from ~/.config/opencode/config.json or a project-level opencode.json.

Auto-configure

bash scripts/install-mcp.sh --agent opencode

Manual configure

Edit ~/.config/opencode/config.json:

{
  "mcp": {
    "moodle-mcp": {
      "command": "python3",
      "args": ["/path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py"],
      "environment": {
        "MOODLE_URL": "https://your-moodle-url/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here",
        "MOODLE_MY_CLASS": "Pagi C",
        "OBSIDIAN_VAULT_PATH": "/home/<you>/Obsidian Vault"
      }
    }
  }
}

Verify

opencode run "list all my Moodle courses"

🖥️ Claude Desktop / Cursor

Go to Claude → Settings → Developer → Edit Config and open claude_desktop_config.json:

{
  "mcpServers": {
    "moodle-mcp": {
      "command": "uvx",
      "args": ["moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle-url/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop. The Moodle tools will appear in the tool picker.

🔌 Advanced: Local Source (No PyPI)

To use the cloned repo directly (useful for development or custom forks):

# From the repo root, install in editable mode
uv pip install -e .

# Then use the local launcher script in MCP configs:
# command: python3
# args: ["/path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py"]

The launcher automatically sets PYTHONPATH so the local src/ is used instead of the installed package.

🛡️ Security Notes

• Never commit your .env file. It contains your Moodle token which grants full API access.

• Tokens are loaded server-side — they are never sent to the AI model directly.

• The .env file is in .gitignore by default.

• For CI/CD, inject MOODLE_URL and MOODLE_TOKEN as environment secrets.

📖 API Reference

Full Moodle Web Service API: Moodle Dev Docs

🤝 Contributing

1. Fork the repo

2. Create a feature branch

3. Write tests (TDD preferred — run PYTHONPATH=src python -m unittest discover -s tests -v)

4. Open a PR

🙏 Acknowledgements

This project is a fork of loyaniu/moodle-mcp with extended features. Full credit to all original contributors:

Additions in this fork

• Phase 2 — Obsidian sync (sync_moodle_to_obsidian, export_deadlines_to_obsidian, export_course_outline)

• Phase 3 — Material downloads (list_course_material_files, download_course_materials, download_assignment_attachments)

• Phase 4 — Assignment submission and feedback tools

• Phase 6 — Calendar events and activity completion tracking

• Polibatam class-slot filter — regex-based multi-class assignment filtering (MOODLE_MY_CLASS)

• Concurrent fetch — 10× speedup for actionable tasks via ThreadPoolExecutor

• Semester auto-archive — detects course rollover and archives the previous semester's Obsidian notes automatically

• Universal install script — one-command setup for Hermes, Claude Code, and OpenCode

📄 License

MIT