unw-planner

A command-line and MCP client for planning courses at the University of Northwestern – St. Paul. It signs in to UNW's Banner 9 Student Self-Service and Ellucian Degree Works audit with an Entra ID + TOTP login, reads the degree audit and course catalog, resolves remaining requirements against real sections, checks time conflicts, and builds term or multi-term plans using Rate My Professors ratings as a soft preference. The same domain layer is exposed as a unwplanner CLI and a stdio MCP server for agent use.

This is an independent project. It is not affiliated with, endorsed by, or supported by the University of Northwestern, Ellucian, or Rate My Professors.

Requirements

• Python 3.11+ (CI covers 3.11 and 3.12).

• A UNW account with access to Banner 9 Student Self-Service and the Degree Works dashboard.

• TOTP two-factor authentication. The login driver generates the current code from a shared secret. Push-notification-only accounts, or tenants that require number matching without a "use a verification code" fallback, cannot be automated.

• Network access to registration-ss.oci.unw.edu, degreeaudit.oci.unw.edu, login.microsoftonline.com and www.ratemyprofessors.com.

Related MCP server: ewm-ops-mcp

One-command install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/HenryGetz/unw-planner/main/bootstrap.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/HenryGetz/unw-planner/main/bootstrap.ps1 | iex

The bootstrap clones to ${UNW_PLANNER_HOME:-$HOME/.unw-planner} (or the Windows equivalent), then runs the interactive installer. It attaches /dev/tty to the setup prompts when available. In CI or another context with no terminal, it refuses to start the interactive prompts and prints the checkout alternative; use the non-interactive command below instead. It installs Python dependencies and Playwright Chromium, writes .env, and optionally logs in.

If you prefer a checkout:

git clone https://github.com/HenryGetz/unw-planner.git
cd unw-planner
./install.sh          # or: sh install.sh

After setup (from the project folder; Windows uses .venv\\Scripts\\unwplanner.exe):

.venv/bin/unwplanner advise --term 202620

advise prints a shareable advising brief: remaining requirements, candidate sections, a conflict-free draft and (with --roadmap) the multi-term plan. It is name-free by default; --no-pii is accepted for scripts that want to be explicit about it.

Non-interactive install (never logs in): pipe the password and provide the other credentials; --no-login still writes .env:

printf '%s\n' "$UNW_PASS" | .venv/bin/unwplanner setup --yes --no-login \
  --password-stdin --user "$UNW_USER" --totp-secret "$UNW_TOTP_SECRET"

CLI

The current commands are listed below. Read-only planning commands beyond this set (profile, remaining requirements, candidates, ratings, conflicts, draft, roadmap, offering matrix) are available through the MCP server; see docs/mcp.md. Every command reads the session written by login; set UNW_AUTO_LOGIN=0 to guarantee no command starts a browser login.

MCP server

unw-mcp runs a stdio MCP server with 20 tools: session health, profile, audit, remaining requirements, terms, search, course detail, candidates, RMP ratings, conflicts, draft (with pins, minimum load and variable-credit hours), roadmap, offering matrix, term-scoped plan operations, a read-only registration preview and a read-only registration time-ticket window.

Plan writes are protected by enforced confirmation, not prose. The four write tools require confirm: true; delete additionally requires confirm_name equal to the plan's exact name. A call without them returns refused: true, the intended effect and the current plan state, and performs no write. Successful writes return a before/after diff read back from Banner.

Register it as a stdio server with an absolute path to <repo>/.venv/bin/unw-mcp (<repo>\\.venv\\Scripts\\unw-mcp.exe on Windows). The shape is the same for omp, Claude Desktop and Cursor:

{
  "mcpServers": {
    "unw-planner": {
      "command": "/ABSOLUTE/PATH/TO/unw-planner/.venv/bin/unw-mcp",
      "args": [],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

Config locations: ~/.omp/agent/mcp.json (omp), the Claude Desktop claude_desktop_config.json, and ~/.cursor/mcp.json (Cursor). unwplanner setup --register-mcp merges this entry into the clients it finds; it preserves other servers and backs up before writing. Restart the client after registering.

See docs/mcp.md for the tool table, real request/response examples, error contract and session-recovery procedure.

What is verified vs unverified

Safety model

• Credentials stay local. UNW_USER, UNW_PASS and UNW_TOTP_SECRET live only in .env (mode 600, gitignored). No code hardcodes them and no command prints them.

• The session state is a secret. .state/unw_state.json is a replayable cookie jar for Banner, Entra ID and Degree Works. It is gitignored and must not be copied into tickets, chat or commits. Overwrite it with unwplanner login --force if exposed.

• No registration writes by default. The MCP server never registers; only the explicit unwplanner snipe command can submit, and only with --live plus --i-understand plus typing the exact term code on stdin. It is browser-driven, dry-run by default, never drops/withdraws, and has not been validated against a live registration window. windows/watch and the MCP registration preview are read-only.

• Plan writes are explicit. CLI plan writes require --yes (and an exact typed plan name for deletes); MCP writes require confirm=true and, for delete, the exact confirm_name. They never run during read commands and never touch anything except Plan Ahead worksheets.

• Captures are never committed. .state/, captures/, .venv/ and caches are gitignored. Capture files may contain course data, screenshots or redacted request logs; keep them local.

• Be polite. The client reuses one session and caches term snapshots for 15 minutes. Do not run a second browser against the same session while an HTTP call is in flight; Banner invalidates the old session.

Known limitations

• Registration is browser-driven and unverified. The direct add/drop endpoints were never observed, so snipe drives the UI. It defaults to a dry run, requires explicit live authorization, and has not been executed against an eligible term. The MCP server has no registration write tool.

• Filtering is client-side. Banner ignores txt_attribute, txt_instructor, chk_open_only and similar parameters on this deployment, so the server fetches a whole-term snapshot (cached for 15 minutes) and filters locally. Seat counts are a snapshot, not live guarantees.

• Plans are term-scoped and bounded. Plan Ahead only works for selectable terms; terms beyond Summer 2027 are visible in the catalog but cannot be planned. An empty plan list means "no plans for this term".

• RMP coverage is thin. Many faculty have no Rate My Professors record or very few ratings. Unrated means unknown, not bad; n<3 is weak evidence.

• Offering patterns are inferred. "Fall-only" or "every-term" comes from seven observed catalog terms, not a registrar guarantee.

• Prerequisite parsing is heuristic. Banner's nested and/or prerequisite text and grade/test clauses are parsed approximately; confirm with an advisor.

• One student per checkout. Settings and state are process-wide, not multi-user.

Porting

The tenant, Banner host, Degree Works host/screen code, RMP school id, term-code convention, attribute vocabulary and login selectors are UNW-specific. docs/porting.md lists every constant/function to change and the tests to add. Contribution rules, including the fixture-scrubbing procedure, are in CONTRIBUTING.md.

Repository layout

Disclaimer

This is unofficial software. Use it only with your own account, at your own risk. Course data, audit results and instructor ratings can be wrong or stale; verify everything with your advisor and the official UNW systems before making enrollment decisions. Respect the terms of service and rate limits of UNW, Ellucian and Rate My Professors. The project is licensed under the MIT License (see LICENSE).