🎓 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 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 (Native Agent & Function Calling)

moodle_mcp includes native support for Google Gemini via the official google-genai SDK and dynamic function calling. Gemini connects to your Moodle session, inspects course contents, evaluates assignment deadlines, and queries your grades.

Setup:

1. Obtain an API key from Google AI Studio.

2. Add your key to .env:

   GEMINI_API_KEY=AIzaSy...
   GEMINI_MODEL=gemini-2.5-flash

Interactive Chat Mode:

Start an interactive terminal conversation where Gemini automatically invokes Moodle tools:

# Using CLI entrypoint
python -m moodle_mcp --mode gemini

# Or using console script
moodle-mcp-gemini

Example interaction:

🎓 Moodle Gemini Assistant — Active (Model: gemini-2.5-flash)
Connected to Moodle instance: https://moodle.tau.ac.il

👤 You: What assignments are due in the next 10 days?
🤖 Gemini is thinking...
You have 2 pending assignments due within the next 10 days:
1. Introduction to Quantum Mechanics — Problem Set 3
   • Due: Sunday, Nov 2, 23:59 (4 days remaining)
   • Status: Not submitted
2. Operating Systems — Assignment 2 (Thread Pools)
   • Due: Thursday, Nov 6, 23:59 (8 days remaining)
   • Status: Draft saved

Single Query CLI Mode:

Ask a single question and receive an immediate answer:

python -m moodle_mcp --mode gemini --prompt "Summarize my grades across all courses"

Programmatic Python Usage:

from moodle_mcp.gemini_client import MoodleGeminiAgent

agent = MoodleGeminiAgent()
response = agent.query_once("What are my deadlines this week?")
print(response)

2. 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.