moodle-mcp

Model Context Protocol server for Moodle LMS — connect Hermes, Claude Code, and OpenCode to your Moodle. Fetch assignments, grades, and deadlines, sync to Obsidian, and get WhatsApp alerts.

Overview • Features • Quick Start • Configuration • Agent Setup • Tools • Obsidian Sync

Overview

moodle-mcp bridges the Moodle Web Services API with the Model Context Protocol, so AI agents can act as your academic assistant. It was built for Polibatam (multi-class filtering) but works with any Moodle instance that has Web Services enabled.

Fork of loyaniu/moodle-mcp — extended from 22 to 40 tools with Obsidian sync, material downloads, submission tools, calendar integration, concurrent fetching, and semester auto-archive.

Features

• Assignments & deadlines — filtered by class slot, sorted by urgency, with actionable task lists

• Grades & progress — course health checks, study load, and completion tracking

• Course content & search — sections, modules, materials, announcements, recent activity

• Obsidian sync — one-command export of dashboards, deadlines, and course notes (with semester auto-archive)

• Material downloads — list and download course files and assignment attachments

• Submissions — submit text, check status, and read feedback

• Calendar — upcoming events, create reminders (H-2), mark activities complete

• Agent-ready — single install-mcp.sh for Hermes, Claude Code, and OpenCode

Quick Start

One-line install

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

Auto-detects installed agents and configures each one. For a dry run:

bash scripts/install-mcp.sh --dry-run

Verify

# Hermes (profile: akademik)
hermes --profile akademik mcp test moodle
# → ✓ Connected  ✓ Tools discovered: 40

# Claude Code
claude mcp list

# Run tests
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v

Configuration

1. Get your Moodle token

1. Open https://<your-moodle>/user/managetoken.php

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

3. Copy the token

2. Create .env

cp .env.example .env

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

# Optional — Polibatam class-slot filter (e.g. Pagi C, Siang A)
MOODLE_MY_CLASS=Pagi C

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

3. Install package

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

# or pip
pip install -e .

Agent Setup

Pick your agent — all use the same local launcher at scripts/moodle_mcp_local_launch.py.

Hermes Agent (recommended)

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

Manual (~/.hermes/profiles/akademik/config.yaml):

mcp_servers:
  moodle:
    command: /home/you/Programming/Python/moodle-mcp/.venv/bin/python
    args: [/home/you/Programming/Python/moodle-mcp/scripts/moodle_mcp_local_launch.py]
    env:
      MOODLE_URL: ${MOODLE_URL}
      MOODLE_TOKEN: ${MOODLE_TOKEN}
      MOODLE_MY_CLASS: "Pagi C"
      OBSIDIAN_VAULT_PATH: "/home/you/Obsidian Vault"

Claude Code

bash scripts/install-mcp.sh --agent claude-code
# or manually
claude mcp add -s user moodle-mcp -- python3 /path/to/moodle-mcp/scripts/moodle_mcp_local_launch.py

Global JSON (~/.claude/settings.json):

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

OpenCode

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

~/.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/webservice/rest/server.php",
        "MOODLE_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Desktop / Cursor

Add to claude_desktop_config.json:

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

Restart the desktop app — tools appear in the picker.

Tools

40 tools across 7 groups. Call them by name from any connected agent (e.g. "list my Moodle courses" → get_my_courses).

Obsidian Sync

Sync creates notes under Academic/Moodle in your vault:

Obsidian Vault/Academic/
  Moodle/                    ← current semester (always up-to-date)
    .semester_courses.json   ← hidden state (course IDs)
    Dashboard.md
    Deadlines.md
    Grades.md
    Courses/
  Archive/
    Semester-2026-07/        ← auto-created on rollover
      Dashboard.md
      Courses/
      Archive-README.md

Semester auto-archive triggers when >50% of course IDs change (or all are new). A single-course swap is ignored.

PYTHONPATH=src python - <<'PY'
from moodle_mcp import api
print(api.sync_moodle_to_obsidian())
PY

Security Notes

• Tokens are loaded server-side and never sent to the model.

• Inject MOODLE_URL / MOODLE_TOKEN as environment secrets in CI.

• moodle.py uses browser-like User-Agent + POST for Cloudflare compatibility.

Acknowledgements

Fork of loyaniu/moodle-mcp — credit to all original contributors:

Additions in this fork

• Obsidian sync + semester auto-archive

• Material downloads & assignment attachments

• Submission & feedback tools, calendar & completion

• Polibatam class-slot filter (MOODLE_MY_CLASS)

• Concurrent fetch (~10× faster actionable tasks)

• Universal install-mcp.sh for Hermes / Claude Code / OpenCode