iclass-mcp

An MCP (Model Context Protocol) server for the Tamkang University (TKU) iClass (TronClass) learning platform.

Connect AI assistants (Antigravity, Claude Desktop, OpenAI Codex / ChatGPT Desktop, Cursor, and other MCP clients) directly to your iClass account to check pending assignments, track deadlines, browse courses and announcements, interact with forum discussions, manage files, and submit homework.

Features

• 📅 Todos & Deadlines: Fetch upcoming and pending homework, quizzes, and exams with due dates.

• 📚 Courses & Syllabi: View ongoing enrolled courses, syllabus structures, and detailed learning activities.

• 📢 Announcements: Read course-level and campus-wide bulletins and notices.

• 💬 Discussion Forums: Browse categories, search/list category topics, read topics/replies, create new discussion threads, post replies, and like topics.

• 📁 Cloud Files: Access your personal iClass cloud storage, upload local files, and download course materials.

• 📝 Assignments & Progress: Mark learning materials as read and submit homework directly.

Related MCP server: seoultech_c4t

Installation & Setup

Prerequisites

• Python 3.10 – 3.13

• A valid TKU SSO account (Student ID and SSO password)

1. Clone the repository

git clone --recurse-submodules https://github.com/GGQQmax/iclass-mcp.git
cd iclass-mcp

2. Quick Install (Automated)

Run the installer for your operating system to automatically initialize git submodules, set up .venv, install requirements, configure .env, and generate client settings:

• Linux & macOS:

  chmod +x install.sh
  ./install.sh

• Windows (PowerShell):

  .\install.ps1

• Windows (Command Prompt / Double Click):

  install.bat

Step A: Configure Environment Variables

Copy the template file to .env:

cp .env.template .env

Edit .env with your student credentials:

USERNAMEID="YOUR_STUDENT_ID"
PASSWORD="YOUR_SSO_PASSWORD"

Step B: Initialize Submodules, Create Virtual Environment & Install Dependencies

git submodule update --init --recursive
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Client Configuration

Antigravity

Add the server definition to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "iclass": {
      "command": "/absolute/path/to/iclass-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/iclass-mcp/iclass_mcp_server.py"],
      "cwd": "/absolute/path/to/iclass-mcp"
    }
  }
}

You can also inspect and manage active MCP servers in the Antigravity UI under Additional Options (...) > MCP Servers.

Codex / ChatGPT Desktop

The repository includes a project-scoped Codex configuration at .codex/config.toml. Update the absolute path to your environment:

[mcp_servers.iclass]
command = "/absolute/path/to/iclass-mcp/.venv/bin/python"
args = ["iclass_mcp_server.py"]
cwd = "/absolute/path/to/iclass-mcp"
default_tools_approval_mode = "prompt"

Open the repository folder in ChatGPT Desktop / Codex and trust the project when prompted.

Alternatively, register the server via the Codex CLI:

codex mcp add iclass -- /absolute/path/to/iclass-mcp/.venv/bin/python /absolute/path/to/iclass-mcp/iclass_mcp_server.py

Claude Desktop

Add the server to your claude_desktop_config.json (located at ~/.config/Claude/claude_desktop_config.json on Linux, or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "iclass": {
      "command": "/absolute/path/to/iclass-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/iclass-mcp/iclass_mcp_server.py"],
      "cwd": "/absolute/path/to/iclass-mcp"
    }
  }
}

Cursor & Other MCP Clients (stdio)

• Command: /absolute/path/to/iclass-mcp/.venv/bin/python

• Args: ["/absolute/path/to/iclass-mcp/iclass_mcp_server.py"]

• Working Directory: /absolute/path/to/iclass-mcp

Available MCP Tools

License

This project is licensed under the Beerware License.