nccu-course-mcp

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.

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.

Recommended: no clone, no venv (needs uv)

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.