Skip to main content
Glama

iGuat-MCP

A read-only MCP (Model Context Protocol) service for iGuihang campus data. Built on Python, FastMCP, and Streamable HTTP, it wraps timetable, class, and campus queries into standard tools callable by AI clients.

This project only provides query capabilities and does not modify the WeChat mini program or upstream academic data.

Features

  • Get the full term list, including the current and next term

  • Search classes by major, grade, and class keyword

  • Get the timetable for a specified class, term, and week

  • Query the timetable for a specified person, removing identity fields before returning

  • Infer the campus from major information

  • Built-in TTL timetable cache, concurrency limits, and health checks

  • Protect the MCP and admin APIs with a Bearer API Key

  • Support hot-updating the upstream token through the admin API

  • Support deployment via Docker, environment variables, and Docker Secrets

Related MCP server: scau-electricity-mcp

MCP Tools

Tool

Description

get_xnxq

Get the full term list, including the current and next term

get_current_term

Get the current term

search_classes

Search classes by criteria

get_class_schedule

Get the timetable for a specified class, term, and week

get_ta_schedule

Query the timetable by name or student ID; identity fields are removed from the response

infer_major_campus

Infer the campus from major information

Tech Stack

  • Python 3.11+

  • MCP / FastMCP

  • HTTPX

  • Uvicorn

  • Pytest

  • Docker

Quick Start

Run Locally

git clone https://github.com/Strayed2SE/iGuat-MCP.git
cd iGuat-MCP

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[test]"

cp .env.example .env
# 按下方说明配置环境变量后启动
python server.py

The service listens on 0.0.0.0:8000 by default:

  • MCP: http://127.0.0.1:8000/mcp

  • Health check: http://127.0.0.1:8000/healthz

MCP client request headers:

Authorization: Bearer <MCP_PUBLIC_API_KEY>

Docker

docker build -t iguat-mcp .
docker run --rm -p 8000:8000 --env-file .env iguat-mcp

For production, use the NAME_FILE form to load sensitive configuration from Docker Secrets or read-only files:

docker run --rm -p 8000:8000 \
  -e IGUAT_USER_TOKEN_FILE=/run/secrets/iguat_token \
  -e IGUAT_MAIN_SIGN_KEY_FILE=/run/secrets/main_sign_key \
  -e MCP_PUBLIC_API_KEY_FILE=/run/secrets/public_key \
  -e MCP_ADMIN_API_KEY_FILE=/run/secrets/admin_key \
  --mount type=bind,src=/secure/secrets,dst=/run/secrets,ro \
  iguat-mcp

Configuration

Copy .env.example and set as needed:

Variable

Purpose

IGUAT_USER_TOKEN

Upstream query token

IGUAT_MAIN_SIGN_KEY

Main API signing key

IGUAT_CLASS_SIGN_KEY

Class API signing key

IGUAT_CSM_SIGN_KEY

CSM API signing key

IGUAT_ALUMNI_SIGN_KEY

Alumni API signing key

IGUAT_SITE_SIGN_KEY

Site API signing key

MCP_PUBLIC_API_KEY

MCP client access key

MCP_ADMIN_API_KEY

Admin API access key

MCP_HOST / MCP_PORT

Service listen address and port

MCP_CACHE_TTL

Timetable cache TTL in seconds; set to 0 to disable caching

MCP_MAX_CONCURRENCY

Maximum concurrency

MCP_MAX_MAJOR_CLASSES

Major class query limit

IGUAT_TRUST_ENV

Whether to read system proxy and certificate environment variables

Update Upstream Token

When the upstream token expires, admins can update the in-memory token without restarting the service:

curl -X PUT http://127.0.0.1:8000/admin/token \
  -H "Authorization: Bearer <MCP_ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"token":"<NEW_TOKEN>"}'

Testing

pip install -e ".[test]"
pytest -q

Security Notes

  • Do not commit real tokens, signing keys, API Keys, or .env to the repository.

  • The service does not return tokens, signatures, or personally identifiable fields to MCP clients.

  • System proxy environment is not read by default; set IGUAT_TRUST_ENV=1 only if your deployment environment actually needs it.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables querying SCAU dormitory electricity usage, balance, lifetime consumption, and cost calculations through read-only MCP tools.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Read-only MCP server for Chaoxing (学习通) that logs into a user's account and exposes their class schedule, enrolled courses, course materials downloads, homework status, exam schedules and scores, chapter task-point progress, notices, and personal cloud drive files. Enables any MCP client to answer natural-language questions about a student's coursework without submitting anything or modifying account data.
      25
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read a student's own university academic data — class timetables, exam schedules, grades, available terms, and empty classrooms — from Qiangzhi (jsxsd) or Zhengfang V9 systems via a session imported from the browser. All access is strictly read-only, never performing course selection, withdrawal, or evaluations.
      6
      1
      MIT