NCCU Course MCP

An MCP server for querying NCCU (National Chengchi University) course listings (qrysub.nccu.edu.tw) programmatically, so an AI assistant or a student can search courses in plain language instead of fighting the web UI.

Course data is fetched live from the public course API on every query; there is no local course database. The only shipped data file is dept_codes.json, a snapshot mapping department codes to names (regenerate any time with build_dept_codes.py).

Tools

• search_all(semester, keyword="", week="", language="", dept="", kind="", core_ge="", teacher=""): school-wide flexible search. The keyword is matched server-side against course names, teachers, notes, and full course ids; narrow further by weekday, teaching language, requirement kind, core-GE flag, or exact teacher. Use this when you don't know which unit offers a course.

• check_schedule(semester, course_ids, extra_times=[]): deterministic conflict check. Give full course ids; returns conflicts + a weekly grid. TA session times mined from course notes are included automatically.

• list_departments(query=""): list offering-unit codes (departments, school-wide subjects, general education, PE, credit programs); filter by a name substring.

• search_courses(semester, dept, keyword=""): courses for one offering unit.

  • semester: academic-year + term, e.g. 1151 = AY115 term 1.

  • dept: unit name or code (e.g. 財務管理學系, 357, or 107 = school-wide Economics).

• get_syllabus(syllabus_url): fetch a course's full syllabus as plain text (description, objectives, learning outcomes, weekly schedule). Restricted to nccu.edu.tw URLs.

Every course comes with structured fields: slots (parsed period list, so models never hand-parse strings like 三CD78) and note_facts (facts mined from the free-text notes: TA session time, exam dates, department priority, add-restriction, English-taught). Query recipes and domain knowledge live in QUERY_GUIDE.md.

Related MCP server: scottylabs-mcp

Install

Using Claude Code? Paste this repo's URL and say "install this MCP server", and it will read the command below and run it for you. Otherwise, copy one command.

Recommended: no clone, no venv (needs uv)

Runs straight from GitHub for Claude Code:

claude mcp add nccu-course -- uvx --from git+https://github.com/yyu0310/nccu-course-mcp nccu-course-mcp

Don't have uv? Install it once: curl -LsSf https://astral.sh/uv/install.sh | sh

No-uv fallback: pip only

Works with any Python 3.10+ (uses pipx to keep it isolated):

pipx install git+https://github.com/yyu0310/nccu-course-mcp
claude mcp add nccu-course -- nccu-course-mcp

Or add to any MCP client's config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "nccu-course": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/yyu0310/nccu-course-mcp", "nccu-course-mcp"]
    }
  }
}

From source

git clone https://github.com/yyu0310/nccu-course-mcp && cd nccu-course-mcp
python -m venv .venv && ./.venv/bin/pip install -e .
./.venv/bin/python src/nccu_course_mcp/test_server.py   # live self-test
claude mcp add nccu-course -- ./.venv/bin/nccu-course-mcp

Notes

• The upstream server uses legacy TLS renegotiation; the client enables OP_LEGACY_SERVER_CONNECT to connect.

• Broad queries are capped at 500 rows upstream, so queries are always scoped per department.

• Uses only NCCU's public course catalog. It touches no private system and no login.