🎓 Moodle MCP Server & OpenAPI Bridge (moodle_mcp)

A high-performance Model Context Protocol (MCP) server and OpenAPI 3.1 gateway in Python that connects LLMs and AI providers (Claude Desktop, Cursor, Antigravity, Gemini, OpenAI, Cline, Windsurf, LangChain) directly to Moodle LMS (specifically configured for Tel Aviv University, but adaptable to any standard Moodle).

Supports both Native FastMCP / MCPServer (stdio, SSE, streamable-http) and Anthropic's OpenAPI MCP approach (via @ivotoby/openapi-mcp-server, awslabs.openapi-mcp-server, or direct FastAPI REST endpoints).

🌟 Highlights

• 🌐 Anthropic OpenAPI MCP Support: Fully compliant OpenAPI 3.1 specification (openapi.json, openapi.yaml) and interactive Swagger UI (/docs). Instantly discoverable by any OpenAPI-to-MCP runner without custom tool adapters.

• 🔐 Zero-Token Session Starting (Preferred): Connects automatically via university SSO credentials (Username + Password + Student ID) or browser session cookies—no master token required! Automatically establishes authenticated sessions, negotiates SAML SSO handshakes, and manages Web Service tokens behind the scenes.

• 🔑 Master Token Tolerant: If you already possess an active Moodle Web Service token (wstoken), you can pass it directly via .env or the moodle_login tool.

• 💾 Persistent Session Caching: Saves active session tokens and cookies securely to ~/.moodle_mcp/session.json so AI assistants remain authenticated across restarts.

• 🔄 Self-Healing Session Recovery: Automatically catches token expiry or session invalidation during long conversations and transparently re-authenticates.

• ⚡ Multi-Threaded REST Engine: Parallelizes assignment queries and grade reports using thread pools, reducing full degree scans from 40+ seconds to ~2 seconds.

• 📚 Full Academic Access:

  • Courses: Enrolled courses with semester, group, and academic year classification.

  • Assignments & Deadlines: True Deadline calculation considering nominal due dates, strict cutoff dates, and individual student extensions.

  • Submissions: Uploads solutions (PDF, ZIP, code) via multipart API or enters online text responses with draft/grading safety flags.

  • Quizzes & Tests: Active and upcoming course quizzes, open/close windows, time limits, and attempt rules.

  • Academic Calendar: Aggregated upcoming deadlines, exam dates, and scheduled classes in one call.

  • Course Announcements: Live updates and notices posted by instructors on news and discussion forums.

  • Course Participants: Teachers, teaching assistants (TAs), and contact emails.

  • Grades & GPA: Gradebook items, formatted scores, percentages, and course average summaries.

  • Course Materials: Section-by-section file listings and download proxy.

  • In-Memory Document Reader: Downloads and parses PDFs (via PyMuPDF), Markdown, TXT, and HTML into AI context on-the-fly without saving to disk.

  • Zoom & Meetings: Automatically extracts live class links and recurring meeting schedules.

  • Panopto Recordings: Discovers lecture videos and recitation (tirgul) recordings.

  • Global Search: Instant fuzzy/keyword search across all courses, tasks, files, and lectures.

Related MCP server: Canvas LMS MCP Server

📋 Table of Contents

1. Architecture & Auth Modes

2. Anthropic's OpenAPI MCP Approach

3. Installation

4. Configuration (.env)

5. Connecting AI Providers

   • Google Gemini (Native Agent & Function Calling)

   • Claude Desktop (Native MCP)

   • Claude Desktop (OpenAPI MCP Approach)

   • Cursor IDE

   • Antigravity

   • AWS Labs OpenAPI MCP Server

   • Cline / Roo Code / Windsurf

   • Docker & Homelab Deployment

   • Python / LangChain / OpenAI

6. Tool Reference

7. Resources & Prompts

8. CLI Options

🔐 Architecture & Auth Modes

flowchart TD
    A["AI Assistant / MCP Client"] --> B{"Connection Approach"}
    B -->|"Native FastMCP (stdio / sse)"| C["moodle_mcp Server"]
    B -->|"Anthropic OpenAPI MCP"| D["OpenAPI Gateway (FastAPI / openapi.json)"]
    D --> C
    C --> E{"Authentication Mode"}
    E -->|"1. SSO Session (Default)"| F["TAU SSO / SAML Handshake<br/>(Extracts MoodleSession & Mobile Token)"]
    E -->|"2. Session Cookie"| G["Direct MoodleSession Cookie<br/>(From browser devtools)"]
    E -->|"3. Master Token"| H["Direct Web Service wstoken"]
    E -->|"4. Standard Moodle"| I["/login/token.php service"]
    F --> J["Local Cache (~/.moodle_mcp/session.json)"]
    G --> J
    H --> J
    I --> J
    J --> K["Moodle REST API & Web Engine"]

1. Zero-Token Session Starting (Recommended)

You only need to supply your SSO credentials in .env (or pass them via the moodle_login tool):

• MOODLE_USERNAME: Your university SSO username.

• MOODLE_PASSWORD: Your password.

• MOODLE_STUDENT_ID: Your 9-digit Israeli ID / Student ID.

The server initiates a headless SAML session handshake with https://nidp.tau.ac.il, logs in, accepts assertions, obtains an active MoodleSession, resets/retrieves an active mobile Web Service token via /user/managetoken.php, and caches it locally.

2. Browser Session Cookie

If you prefer not to enter credentials, copy the value of your MoodleSession cookie from your browser devtools (Storage -> Cookies -> moodle.tau.ac.il):

MOODLE_SESSION_COOKIE=abc123xyz...

3. Master Web Service Token (wstoken)

If you already have an active Moodle Web Service token:

MOODLE_TOKEN=your_32_character_token_here

🌐 Anthropic's OpenAPI MCP Approach

Anthropic's Model Context Protocol supports bridging standard REST APIs directly into AI models using OpenAPI specifications. This gives you full flexibility to run moodle_mcp through any OpenAPI runner without custom client coding.

1. Start the OpenAPI REST Gateway

# Starts the FastAPI OpenAPI gateway on port 8000
python -m moodle_mcp --mode openapi --port 8000

• Interactive Swagger UI: http://localhost:8000/docs

• ReDoc Documentation: http://localhost:8000/redoc

• Live OpenAPI 3.1 Spec: http://localhost:8000/openapi.json

2. Connect via OpenAPI MCP Runner (@ivotoby/openapi-mcp-server)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "moodle-openapi": {
      "command": "npx",
      "args": [
        "-y",
        "@ivotoby/openapi-mcp-server",
        "http://localhost:8000/openapi.json"
      ]
    }
  }
}

3. Connect via AWS Labs OpenAPI MCP Server

{
  "mcpServers": {
    "moodle-openapi": {
      "command": "uvx",
      "args": [
        "awslabs.openapi-mcp-server@latest",
        "--spec",
        "https://raw.githubusercontent.com/duck-5/moodle-mcp/main/openapi.json"
      ]
    }
  }
}

4. Export Static OpenAPI Files

You can export the OpenAPI specification at any time:

python -m moodle_mcp --export-openapi .

This generates openapi.json and openapi.yaml in the current directory.

🚀 Installation

Ensure Python 3.10+ is installed:

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

# Install dependencies
pip install -r requirements.txt

# Or install as an editable package
pip install -e .

Verify your installation:

python -m moodle_mcp --status

⚙️ Configuration (.env)

Create a .env file in the root of the project (copy from .env.example):

# Base URL of your Moodle instance
MOODLE_URL=https://moodle.tau.ac.il

# Option 1: Zero-Token SSO Session Starting (Recommended)
MOODLE_USERNAME=your_username
MOODLE_PASSWORD=your_password
MOODLE_STUDENT_ID=123456789

# Option 2: Master Web Service Token (Optional)
# MOODLE_TOKEN=your_moodle_web_service_token

# Option 3: Browser Session Cookie (Optional)
# MOODLE_SESSION_COOKIE=your_session_cookie

# Timezone (defaults to Asia/Jerusalem)
TIMEZONE=Asia/Jerusalem

🤖 Connecting AI Providers

1. Google Gemini & Antigravity (MCP Server Integration)

Google Gemini (via Gemini CLI, Antigravity, and Gemini Enterprise) supports connecting to MCP servers using two official transport protocols:

1. stdio (Local Subprocess): Gemini launches the Python process and communicates over stdin/stdout via JSON-RPC.

2. streamable-http (Remote HTTP/HTTPS): Gemini connects over modern Streamable HTTP to /mcp. (Note: Google Gemini explicitly does not support legacy HTTP+SSE; it requires Streamable HTTP).

Protocol A: Stdio Transport (Local / Docker)

Add to your Gemini configuration file (~/.gemini/config/mcp_config.json):

Direct Python:

{
  "mcpServers": {
    "moodle": {
      "command": "/path/to/moodle-mcp/.venv/bin/python",
      "args": [
        "-m",
        "moodle_mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "MOODLE_URL": "https://moodle.tau.ac.il",
        "MOODLE_USERNAME": "your_username",
        "MOODLE_PASSWORD": "your_password",
        "MOODLE_STUDENT_ID": "123456789"
      }
    }
  }
}

Via Docker:

{
  "mcpServers": {
    "moodle": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "moodle-mcp",
        "python",
        "-m",
        "moodle_mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

Protocol B: Streamable HTTP Transport & OAuth 2.1 (Gemini Web, Cloudflare Tunnel, Remote)

Start the Moodle MCP server in streamable-http mode:

python -m moodle_mcp --transport streamable-http --host 0.0.0.0 --port 8000

🌟 Multi-User Zero-Configuration with Gemini Web

moodle_mcp supports OAuth 2.1 with PKCE, Dynamic Client Registration (RFC 7591), and Protected Resource Discovery (RFC 9470 / RFC 8414). This allows any number of different users to connect to the exact same MCP server URL (e.g., https://moodle-mcp.mantin.dev/mcp or http://localhost:8000/mcp) with zero server-side pre-configuration:

1. Add MCP Server in Gemini Web:

   • Open Gemini -> Settings -> Connected Tools -> Add MCP Server.

   • Server URL: https://moodle-mcp.mantin.dev/mcp (or http://localhost:8000/mcp)

   • Authentication Type: OAuth 2.0

2. Authenticate Once:

   • Option 1: Browser SSO Login (Recommended): Leave Client ID and Client Secret empty and click Next. A secure popup will open with the TAU SSO login screen. Sign in once with your university username, student ID, and password.

   • Option 2: Direct Credentials: In Gemini's modal, enter your TAU SSO username (or username:student_id) in Client ID and your password in Client Secret for instant zero-popup setup.

3. Enjoy Transparent, Zero-Prompt Academic AI:

   • Gemini stores the encrypted OAuth token.

   • You never need to log in again during future conversations or tool calls.

   • Self-Healing Session Recovery: If TAU Moodle's session expires after a few hours, the server transparently and silently re-authenticates in the background without interrupting your chat.

   • Stateless Multi-User Isolation: Different users connecting to the exact same URL are completely isolated into their own in-memory sessions with their own courses, assignments, and grades.

Gemini CLI (mcp_config.json) Configuration:

{
  "mcpServers": {
    "moodle": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Or when exposed via Cloudflare Tunnel:

{
  "mcpServers": {
    "moodle": {
      "url": "https://moodle-mcp.mantin.dev/mcp"
    }
  }
}

2. Standalone Gemini Agent (Direct Script & CLI)

If you also wish to chat directly with Gemini from the terminal using function calling without an external MCP host:

# Add GEMINI_API_KEY to your .env
python -m moodle_mcp --mode gemini

3. Claude Desktop (Native MCP)

Add moodle to your claude_desktop_config.json:

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

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

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": [
        "-m",
        "moodle_mcp"
      ],
      "env": {
        "MOODLE_URL": "https://moodle.tau.ac.il",
        "MOODLE_USERNAME": "your_username",
        "MOODLE_PASSWORD": "your_password",
        "MOODLE_STUDENT_ID": "123456789"
      }
    }
  }
}

Restart Claude Desktop, and click the 🔨 hammer icon to see all Moodle tools!

3. Claude Desktop (OpenAPI MCP Approach)

Start the OpenAPI server (python -m moodle_mcp --mode openapi --port 8000) and configure:

{
  "mcpServers": {
    "moodle": {
      "command": "npx",
      "args": [
        "-y",
        "@ivotoby/openapi-mcp-server",
        "http://localhost:8000/openapi.json"
      ]
    }
  }
}

4. Cursor IDE

In Cursor, go to Settings -> Features -> MCP, or edit .cursor/mcp.json:

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["-m", "moodle_mcp"]
    }
  }
}

5. Antigravity

In your Antigravity project configuration:

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["-m", "moodle_mcp"]
    }
  }
}

6. AWS Labs OpenAPI MCP Server

{
  "mcpServers": {
    "moodle": {
      "command": "uvx",
      "args": [
        "awslabs.openapi-mcp-server@latest",
        "--spec",
        "openapi.json"
      ]
    }
  }
}

7. Cline / Roo Code / Windsurf

Configure in cline_mcp_settings.json:

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["-m", "moodle_mcp"],
      "disabled": false,
      "autoApprove": [
        "moodle_get_enrolled_courses",
        "moodle_get_upcoming_assignments",
        "moodle_get_grades_summary",
        "moodle_get_calendar_events",
        "moodle_search"
      ]
    }
  }
}

8. Docker & Homelab Deployment

Deploy moodle_mcp as a zero-trust container attached to mcp-gateway-net and exposed via Cloudflare Tunnel:

# Build and start in background
docker compose up -d

# Check health status
docker compose ps
curl http://localhost:8000/health

Run Gemini Agent Inside Docker:

docker compose exec moodle-mcp python -m moodle_mcp --mode gemini

Cloudflare Tunnel Exposure:

Point your Cloudflare Tunnel hostname (moodle.yourdomain.com) to: http://moodle-mcp:8000

This instantly provides:

• Live Swagger UI at https://moodle.yourdomain.com/docs

• OpenAPI Specification at https://moodle.yourdomain.com/openapi.json for Vertex AI Extensions or external LLMs.

9. Python / LangChain / OpenAI

Run the server over SSE or streamable-http for networked AI agents:

# Start SSE server on port 8000
python -m moodle_mcp --transport sse --port 8000

Connect using the Python MCP client:

from mcp.client.sse import sse_client
from mcp import ClientSession

async with sse_client("http://localhost:8000/sse") as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        print("Available tools:", [t.name for t in tools.tools])

🛠️ Tool Reference

📦 Resources & Prompts

Resources

• moodle://profile: Current user details and Moodle site configuration.

• moodle://courses: Real-time list of enrolled courses.

• moodle://upcoming: Chronological list of deadlines in the next 7 days.

• moodle://grades: Summary of course grades and averages.

• moodle://quizzes: Active and upcoming course quizzes.

• moodle://calendar: Academic calendar events for the next 14 days.

• moodle://announcements: Course announcements and forum notices.

• moodle://saved: Metadata list of all named items in persistent storage.

• moodle://cache: Status and entry ages of the automatic API cache.

Prompts

• study_briefing: Summarizes current courses, upcoming deadlines, and study priorities.

• assignment_analysis: Inspects assignment instructions, parses attached PDFs, and outlines requirements and completion steps.

• exam_preparation: Analyzes course syllabus, upcoming exam dates, past materials, and announcements for targeted exam preparation.

💻 CLI Options

# Check current authentication status
python -m moodle_mcp --status

# Interactive SSO login CLI (prompts for password securely)
python -m moodle_mcp --login-sso

# Interactive Gemini AI assistant with real-time Moodle tool calling
python -m moodle_mcp --mode gemini

# One-off Gemini question from terminal
python -m moodle_mcp --mode gemini --prompt "What deadlines do I have next week?"

# Run standard stdio MCP server (for Claude Desktop, Cursor, Antigravity)
python -m moodle_mcp --transport stdio

# Run SSE server for network / remote AI agents
python -m moodle_mcp --transport sse --port 8000 --host 0.0.0.0

# Run streamable-http MCP server
python -m moodle_mcp --transport streamable-http --port 8000

# Run FastAPI OpenAPI REST Gateway (Anthropic OpenAPI approach)
python -m moodle_mcp --mode openapi --port 8000

# Export static OpenAPI 3.1 specification (openapi.json and openapi.yaml)
python -m moodle_mcp --export-openapi .

🛡️ Security & Privacy

1. Client-Only Architecture: moodle_mcp communicates directly from your machine to Moodle. No third-party servers, relays, or cloud proxies are involved.

2. Encrypted at Rest: Persistent sessions in ~/.moodle_mcp/session.json reside strictly on your local disk in your user profile.

3. Draft Safety: moodle_submit_assignment defaults to saving files as drafts (submit_for_grading=False), preventing accidental locking of assignments before you verify them.

4. Git Protection: Strict .gitignore ensures credentials, tokens, and session caches are never committed to version control.

📄 License

MIT License. See LICENSE for details.