🎓 Moodle MCP Server

🌟 Overview

Moodle MCP Server empowers AI assistants (like Claude Code, Claude Desktop, Cursor, and custom MCP clients) to seamlessly query course syllabi, assignment deadlines, calendar events, lecture materials, announcements, and participants from IIIT Hyderabad's Moodle LMS.

Built with a hybrid HTTP-first engine, it delivers sub-50ms query latency via persisted session cookies while maintaining a resilient Playwright fallback for dynamic JavaScript rendering.

┌─────────────────┐       MCP (stdio / SSE)       ┌────────────────────────┐
│   Claude Code   │ ◄───────────────────────────► │   Moodle MCP Server    │
│  Claude Desktop │                               │   (FastMCP Engine)     │
└─────────────────┘                               └───────────┬────────────┘
                                                              │
                                     ┌────────────────────────┴────────────────────────┐
                                     ▼                                                 ▼
                          ⚡ Fast HTTP (httpx)                            🎭 Playwright Browser
                          • Cached Cookie Transport                       • Dynamic JS Fallback
                          • Latency < 50ms                                • Interactive CAS SSO
                                     │                                                 │
                                     └────────────────────────┬────────────────────────┘
                                                              ▼
                                                 🏛️ IIIT Moodle Instance
                                                   (courses.iiit.ac.in)

Related MCP server: dutic-mcp

✨ Key Features

• ⚡ Sub-50ms Latency (Hybrid Engine) — Requests hit a fast async HTTP transport using authenticated cookie state, falling back to headless Chromium only for dynamic DOM rendering.

• 🔒 Zero-Password Security — Passwords and MFA tokens are never requested, stored, or logged. Authentication occurs via interactive CAS SSO in a visible browser window.

• 🛡️ MCP Safety Annotations — Complies with the latest MCP specification, flagging all endpoints with readOnlyHint=True and destructiveHint=False.

• 🧠 Native Claude Skill Included — Comes with .claude/skills/moodle.md for zero-configuration, natural conversational workflows in Claude Code.

• 📅 Smart Date & Deadline Normalization — Automatically normalizes Moodle deadlines into ISO-8601 strings while preserving human-readable relative dates (Tomorrow, 11:59 PM).

• 🍓 Lightweight & Cross-Platform — Runs effortlessly on Windows, macOS, Linux, and resource-constrained environments like Raspberry Pi 4B (ARM64).

• 🔄 Multi-Transport Support — Native support for both stdio (CLI / Claude Desktop) and SSE (Network / Remote MCP clients).

🛠️ MCP Tools Reference

The server exposes 9 specialized read-only tools designed for structured LLM querying:

class Course(BaseModel):
    id: str
    name: str
    url: str

class Assignment(BaseModel):
    course: str
    name: str
    due_date: Optional[str]      # ISO 8601 (e.g. "2026-09-20T23:59:00")
    due_date_raw: str            # Display string (e.g. "Sunday, 20 September, 11:59 PM")
    status: str                  # "submitted" | "not_submitted" | "graded"
    url: str

class CalendarEvent(BaseModel):
    title: str
    date: Optional[str]          # ISO 8601
    date_raw: str
    course: Optional[str]
    event_type: str              # "assignment_due" | "workshop_submission" | "course_event"
    url: Optional[str]

🚀 Installation & Setup

1. Prerequisites

• Python 3.9+ (Tested up to Python 3.14)

• Chromium (Managed automatically via Playwright)

• Compatible with Windows, macOS, Linux, and Raspberry Pi (aarch64)

2. Clone & Setup Environment

# Clone the repository
git clone https://github.com/blank6890/moodle-mcp-server.git
cd moodle-mcp-server

# Create and activate virtual environment
python -m venv venv

# On Linux / macOS:
source venv/bin/activate

# On Windows (PowerShell):
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install Playwright browser binary
playwright install chromium

🔐 Authentication (Interactive CAS Login)

Moodle requires CAS SSO credentials. To protect your security, the server never handles passwords directly.

Run the interactive login script:

python scripts/login.py

============================================================
Moodle Interactive Login
============================================================
Opening Moodle login page...
Waiting for login (up to 5 minutes)...
Complete CAS login in the browser window.
✓ Login successful!
✓ Session cookies saved to ./session/state.json

1. A visible Chromium window will launch displaying the IIIT CAS Login page.

2. Complete your login (enter your username, password, and 2FA/CAPTCHA if prompted).

3. Once authenticated, cookies are securely saved to ./session/state.json.

4. The browser closes automatically. Your session is now ready!

💡 Session Expired? If your session expires after several days, simply run python scripts/login.py again to refresh ./session/state.json.

🤖 Claude Integration

Option A: Connect to Claude Code (CLI)

Add the MCP server to Claude Code with persistent session configuration:

claude mcp add moodle python -s local -e SESSION_DIR=./session -e PYTHONPATH=. -- -m app.main

Option B: Connect to Claude Desktop

Add this configuration to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["-m", "app.main"],
      "cwd": "/path/to/moodle-mcp-server",
      "env": {
        "PYTHONPATH": ".",
        "SESSION_DIR": "./session"
      }
    }
  }
}

(Replace /path/to/moodle-mcp-server and python with the absolute paths to your project directory and virtual environment Python interpreter).

Option C: Standalone Server

You can also run the server directly:

# Standard I/O mode (for MCP clients)
python app/main.py

# Server-Sent Events (SSE) mode (for remote connections)
python app/main.py --sse

💬 Conversational Examples

Once connected, you can interact with Moodle using natural language:

⚙️ Configuration

Customize runtime behavior via environment variables or a .env file:

⚡ Performance & Benchmarks

The built-in hybrid architecture avoids spawning a heavy browser process for every query:

Run the benchmark suite locally:

python scripts/benchmark_latency.py

🔒 Security & Privacy

1. Zero Credential Exposure: Your Moodle password and 2FA credentials are never passed as command-line arguments, environment variables, or tool inputs.

2. Local Session Vault: Cookies are saved locally in ./session/state.json (ignored in .gitignore).

3. Strictly Read-Only: The server implements query tools only. It cannot submit assignments, post forum messages, modify profile details, or delete files.

4. Sanitized Tool Outputs: Tool outputs sanitize raw session tokens, ensuring sensitive headers or auth keys are never sent in LLM context windows.

🧪 Testing & Verification

The project includes an extensive automated test suite covering HTTP clients, browser managers, data models, and HTML parsers:

# Run full test suite
pytest

# Run tests with verbose output
pytest -v

# Run with test coverage
pytest --cov=app tests/

❓ Troubleshooting

CAS sessions expire periodically based on university security policies. Simply run:

python scripts/login.py

Log in once, and the server will immediately resume operating without needing a restart.

Ensure Chromium is installed for Playwright:

playwright install chromium

If using a custom Chromium binary (e.g. on Raspberry Pi), set the environment variable:

export CHROMIUM_PATH="/usr/bin/chromium"

Set LOG_LEVEL=DEBUG in your environment:

export LOG_LEVEL=DEBUG
python app/main.py

📄 License

Distributed under the MIT License. See LICENSE for more information.