METU ODTUClass MCP Server

A Model Context Protocol (MCP) server for METU's ODTUClass learning management system — enabling AI assistants to query courses, announcements, syllabi, assignment deadlines, and lab schedules directly from odtuclass.metu.edu.tr.

Overview

This server bridges your AI assistant (Antigravity IDE, Claude Desktop, or any MCP-compatible client) with ODTUClass — METU's Moodle-based learning platform. Once connected, you can ask your AI to:

• "What courses am I enrolled in this semester?"

• "Show me the latest announcements from PHYS 106."

• "Download and summarize the syllabus for MATH 130."

• "What assignments are due this week?"

• "When is my CENG 242 Section 3 recitation?"

Related MCP server: SABIS MCP Server

Available MCP Tools

All student_token parameters are optional when credentials are configured via environment variables or .env.local.

Authentication

Two methods are supported. Credentials-based login is recommended — it requires no manual token extraction.

Option A — METU Username & Password (Recommended)

Set your credentials in .env.local (gitignored, never committed):

ODTUCLASS_USERNAME=e123456
ODTUCLASS_PASSWORD=your_metu_password

The server reads this file on startup, authenticates automatically, and securely caches the session token in .odtuclass_cache/session.json. Subsequent runs reuse the cached token.

You can also ask the AI to log in explicitly:

"Log in to ODTUClass with username e123456 and password ..."

Option B — Web Service Token (Security Key)

1. Visit ODTUClass and log in.

2. Click your name in the top-right → Preferences.

3. Under User Account, open Security keys.

4. Copy the Moodle mobile web service token (32-character alphanumeric string).

Then set it in .env.local:

ODTUCLASS_TOKEN=your_32_character_token

Installation

Prerequisites

• Python 3.10 or later

• pip (or uv)

1. Clone the Repository

git clone https://github.com/your-username/metu-odtuclass-mcp.git
cd metu-odtuclass-mcp

2. Create a Virtual Environment

python -m venv .venv
.venv\Scripts\activate   # Windows
source .venv/bin/activate  # macOS / Linux

3. Install Dependencies

pip install -r requirements.txt

4. Configure Credentials

cp .env.example .env.local
# Edit .env.local with your METU username/password or token

Client Configuration

Antigravity IDE

Add the following to your workspace .agents/mcp_config.json or global ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "odtuclass": {
      "command": "/path/to/metu-odtuclass-mcp/.venv/Scripts/python.exe",
      "args": ["/path/to/metu-odtuclass-mcp/odtuclass_mcp.py"],
      "env": {
        "ODTUCLASS_BASE_URL": "https://odtuclass.metu.edu.tr"
      }
    }
  }
}

Credentials are loaded automatically from .env.local — keep them out of mcp_config.json.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "odtuclass": {
      "command": "/path/to/.venv/Scripts/python.exe",
      "args": ["/path/to/metu-odtuclass-mcp/odtuclass_mcp.py"]
    }
  }
}

Selecting a Semester

ODTUClass runs on semester-specific subdomains. The server auto-discovers the active semester by following redirects from odtuclass.metu.edu.tr. To target a specific past semester, set ODTUCLASS_BASE_URL:

Running & Testing

Start the MCP Server

python odtuclass_mcp.py

Interactive Live Test (Multi-Semester)

python test_live.py

Prompts for semester selection, authenticates, and tests course listing, assignment deadlines, announcements, and syllabus fetching interactively.

Visual MCP Inspector (Browser UI)

mcp dev odtuclass_mcp.py

Opens a local browser UI to browse tools and execute them with custom parameters.

Unit Tests

python -m unittest discover tests -v

Project Structure

metu-odtuclass-mcp/
├── odtuclass_mcp.py          # MCP server definition and tool handlers
├── odtuclass_client.py       # ODTUClass Moodle REST API client
│                             #   · Semester auto-discovery
│                             #   · Credential-based login
│                             #   · Secure session token caching
│                             #   · File download management
├── models.py                 # Pydantic data models and type definitions
├── requirements.txt          # Runtime dependencies
├── pyproject.toml            # Package configuration
├── test_live.py              # Interactive multi-semester live test script
├── .env.example              # Environment variable template (safe to commit)
├── .env.local                # Your local credentials (gitignored)
├── .odtuclass_cache/         # Session token cache (gitignored)
├── downloads/                # Downloaded course files (gitignored)
└── tests/
    ├── __init__.py
    └── test_odtuclass.py     # Unit and mock test suite (21 tests)

Security Notes

Never put your METU password directly in mcp_config.json or any committed file. Use .env.local instead.

License

This project is licensed under the terms of the MIT License.