Skip to main content
Glama
NCCU Course MCP

NCCU Course MCP

by yyu0310

NCCU Course MCP

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

Not sure where to start? Paste this to your AI coding agent (Claude Code, Codex, etc.):

Install this MCP server https://github.com/yyu0310/nccu-course-mcp

It can run every step below on its own, except one password step later in this page that only you should type. Works with Claude Code and the Claude Desktop app (both run on your own machine). The claude.ai web app and mobile app can't run local MCP servers like this one, so they're not an option here.

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

You don't need to remember any tool name or parameter, just tell your AI agent what you want (e.g. "find me courses offered by the Finance department" or "does this course clash with my Wednesday afternoon class"), and it picks the right tool on its own. This table is for anyone curious what happens under the hood.

What it does

Details

When you'd reach for it

Tool name

School-wide flexible search

Keyword search across course names, teachers, notes, and course ids, narrowable by weekday, language, requirement kind, core-GE, or exact teacher

You don't know which department offers a course

search_all

Schedule conflict check

Give a list of course ids, get back conflicts plus a weekly grid. TA session times are folded in automatically

Checking whether your picked courses collide

check_schedule

Department code lookup

Lists every offering-unit code (departments, school-wide subjects, general ed, PE, credit programs), filterable by name

You don't know a department's code or exact name

list_departments

Courses by department

Course list for one offering unit in one semester

You already know which department to search

search_courses

Full syllabus

Description, objectives, learning outcomes, weekly schedule

Deciding whether to take a course

get_syllabus

Teaching ratings (optional)

A teacher's evaluation scores and written comments for the last six semesters (NCCU policy caps this window)

Checking a teacher's evaluation history, needs your own NCCU login, password privacy explained below

get_course_rating

Every other tool is anonymous and needs no login, the ratings tool is the one exception.

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

AI agent doing this install? Run the command in this section yourself, no need to ask the human for anything yet. Stop before the "Optional" section below and read its instructions first, that section has one step you must never run on the human's behalf.

Runs straight from GitHub for Claude Code.

Step 0: make sure uvx exists. Run uvx --version. If the command is not found, install uv once, then load it into the current shell (the installer puts it in ~/.local/bin, which is not on PATH yet):

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"

On Windows (PowerShell), install uv with the command below, then open a new PowerShell window so uvx is on PATH:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 1: register the server.

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

The first claude mcp list health check downloads and builds the package, so it can take 10 to 60 seconds. If it shows "Failed to connect" and your editor or GUI app launched Claude Code without the new PATH, re-register with the full path: claude mcp add nccu-course -- ~/.local/bin/uvx --from git+https://github.com/yyu0310/nccu-course-mcp nccu-course-mcp.

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

Optional: course ratings (get_course_rating)

Every other tool is anonymous and needs nothing set up. get_course_rating is the one exception: NCCU only shows a teacher's rating history to logged-in students, so this tool needs your own NCCU login. Skip this whole section if you don't need it, everything else works unaffected.

Step 1 (you do this yourself, not your AI agent)

Save your NCCU portal password to your computer's credential store, once. If an AI agent is helping you install this, do not let it run this command or type your password for you. Open your own terminal and run it yourself:

uv run --with keyring python -c "import keyring; keyring.set_password('nccu-ldap', '<your student id>', input())"

(uv run --with keyring fetches keyring for this one command, so nothing needs installing first. It needs the uv from the Install section.)

It will ask for your password and hide what you type. This uses keyring, which is verified on macOS (Keychain) and Windows 11 (Credential Manager). Linux (Secret Service) should work the same way in theory, but I haven't tested it. Your password never touches disk in plaintext and is never logged, by this tool or by whatever agent is helping you set it up.

Step 2 (your AI agent can do this for you)

Tell it your student ID (not a secret, just needed to know whose tracking list to use) and have it set NCCU_STUDENT_ID wherever the server runs, for example in the MCP client config:

{
  "mcpServers": {
    "nccu-course": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/yyu0310/nccu-course-mcp", "nccu-course-mcp"],
      "env": { "NCCU_STUDENT_ID": "<your student id>" }
    }
  }
}

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 and requires no login, except for the optional get_course_rating tool described above.

Further reading

New to Claude Code itself, not just this tool? claude-code-security-starter is a starter pack of CLAUDE.md rules and hooks that block credential leaks before they happen, a good first project to install.

Available Tools

3 tools
get_syllabusA

讀取一門課的教學大綱全文(純文字)。

syllabus_url 用 search_courses 回傳的 syllabus_url 欄位。 內容含課程簡介、課程目標與學習成效、每週進度、評分方式等,可據以判斷課程性質。

Inputs: syllabus_url (required). Returns: result

list_departmentsA

列出政大系所代碼表(snapshot)。傳 query 以官方系名子字串篩(如『財務』『法律』;用全名非簡稱)。

回傳每筆: code(三碼)、name(中文系名)、level(大學部/研究所/學程)、course_count(snapshot 當時開課數)。 code 首碼=學院、中間碼=學制(0大學部/5碩士)、可直接餵給 search_courses。

Inputs: query. Returns: result

search_coursesA

查某系所某學期的開課清單(即時查政大 API)。

參數: semester: 學期碼,格式『學年+學期』,如 1151 = 115學年第1學期、1142 = 114學年第2學期。 dept: 系所中文名或三碼代碼,如『財務管理學系』或『357』。用 list_departments 查代碼。 keyword: 選填。以關鍵字篩課名/教師/備註(如『交易』『個案』)。

回傳: {semester, dept_code, dept_name, count, courses:[...]}。 每門課含 course_id/name/teacher/time/credits/kind/target/classroom/language/note/ remain_url(即時餘額需另開)/syllabus_url。

Inputs: dept (required), semester (required), keyword.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct purpose: listing departments, searching courses, and retrieving syllabus. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (list_departments, search_courses, get_syllabus), making them predictable.

    Tool Count4/5

    Three tools is slightly minimal but appropriate for a focused read-only server. The tools cover the essential query flow without unnecessary extras.

    Completeness4/5

    The tool surface covers the core workflow (list departments, search courses, get syllabus). Minor gaps like direct course detail retrieval are addressed by search_courses returning rich data.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers