unw-mcp
Provides read-only access to the university's public Google ICS academic calendar, enabling retrieval of upcoming semester dates, breaks, and deadlines through the unw_calendar academic, breaks, and deadlines operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@unw-mcp what's my dining balance and today's lunch menu?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
unw-mcp
Read-only, token-efficient MCP server for the University of Northwestern – St. Paul
student portal (my.unw.edu). It signs in through the portal's SAML/Entra flow using a
persistent Chromium profile, then projects portal and Banner data into compact JSON for an
assistant.
Status: phase 3 / first release — session, dashboard, academics, finances, dining, academic calendar and page search. Read-only.
⚠️ Unofficial — use at your own risk
This is an unofficial personal project. It is not affiliated with, endorsed by, or supported by University of Northwestern – St. Paul, Pathify, Ellucian, Microsoft, or Bon Appétit. Use your own account, comply with every applicable term and policy (automation may violate them), and verify anything that matters against the official portal. There is no warranty and no liability for account lockout, data loss, policy/FERPA problems, or decisions made from the data. No credentials or PII are included in this repository — your local credentials and profile are yours to protect.
Read DISCLAIMER.md before running anything. Licensed under the
MIT License.
Related MCP server: USTC School MCP
Surface
Tool | Ops | Backing endpoints | Cache | Returns |
|
|
| — | authenticated flag, auth method, cookie lifetimes (no values) |
|
| profile + notices + tasks + today's events | 2–10 min | identity, degree progress, advisors, 3 notices, 5 pending tasks, today's events |
| today's classes + next-24h events + tasks + notices + next meal | 2–10 min (reuses caches) | plan-my-day: 8 classes, 8 de-duplicated events ( | |
|
| 2 min | title, type, preview, dates, ack flag | |
|
| 2 min | title, preview, due, required/complete, link | |
|
| 5 min | title, start/end, local time, all-day, location, calendar | |
|
| 10 min | card title + label/url pairs | |
|
|
| 10 min | name, e-mail, role, GPA, degree progress, advisors, hold |
|
| 10 min | today's classes with local times and rooms | |
| same, requested/current term | 10 min | course, CRN, title, credits, instructors, meetings (days/times/room/dates) | |
| same history endpoint for recent completed terms | 30 min | graded courses per term, credits | |
|
| 30 min | overall GPA/hours plus per-level rows | |
|
| 5 min | description, type, dates, releasable, amount owed | |
|
| 5 min | standing, allowsRegistration, status, time-ticket state | |
|
| none (claims 300 s) | degree/major/minor names, percent, credits, GPA, requirements; | |
|
|
| 5 min | Student Account and Dining Funds amounts |
|
| 60 min | aid year, award rows, per-period totals, cost rows and total | |
|
| 15 min | credits earned/required, remaining, percent, period | |
|
|
| 60 min | cafe name, address, plain-text hours/message |
| same projected dataset | 60 min | requested date's cafes → dayparts → stations → item labels; | |
| same | 60 min | 7 rolling dates, daypart item/station counts and samples; | |
|
| public Google ICS discovered from | 6 h | upcoming semester/break/deadline dates |
| same | 6 h | recess/holiday/no-classes rows | |
| same | 6 h | add/drop, withdraw, registration and other deadlines | |
|
| 5 min | campus events filtered to the local-date window | |
|
|
| 10 min | ranked slug/title/category/excerpt; exact title/slug first; |
|
| 24 h | plain-text body (4,000-char cap), body_chars, body_truncated |
Output rules enforced in code: 5–12 fields per row, HTML stripped, ISO and
America/Chicago local times, nulls omitted, lists capped, no raw Pathify/Banner
envelopes. The portal's event count is global, so events are filtered client-side to the
requested local-date window (days, default 7; 0 = today).
Arguments are shared per tool to keep schema tokens low:
unw_session { op }
unw_dashboard { op, limit?, days?, include_completed? } # op=day takes no extra args
unw_academics { op, term? } # term: Banner code (202610) or name (Fall 2026)
unw_finances { op, aid_year? } # aid_year: code (2627) or label (2026-2027)
unw_dining { op, date?, cafe?, meal?, detail? } # detail defaults to brief
unw_calendar { op, days?, limit?, query? } # query filters academic/breaks/deadlines titles
unw_pages { op, query?, slug?, limit?, excerpt_chars? }Install (no clone)
Requirements: Node >= 22 and Playwright Chromium (npx playwright install chromium); a Linux
desktop/Xvfb only if you set headless: false.
Point your MCP client at the GitHub repository directly — npm fetches the source, installs
devDependencies, runs prepare (npm run build) and links the unw-mcp binary. No clone, no
local build:
{
"mcpServers": {
"unw": {
"command": "npx",
"args": ["-y", "github:HenryGetz/unw-mcp"],
"env": { "UNW_MCP_TIMEZONE": "America/Chicago", "UNW_MCP_HEADLESS": "1" }
}
}
}Other installs:
npx -y github:HenryGetz/unw-mcp # run once (stdio; the client normally spawns it)
npm pack github:HenryGetz/unw-mcp # builds dist/ inside the tarball
npm install -g ./unw-mcp-0.1.0.tgz # global `unw-mcp` commandUse the tarball form for a global install: npm install -g github:HenryGetz/unw-mcp is
unreliable because npm ≥ 11 runs the git checkout's build with the global install's flags
inherited, so the build fails inside the checkout (npm error git dep preparation failed).
That is an npm limitation, not a problem with the tarball or npx path.
Or let add-mcp write the client config for you
(claude-code, claude-desktop, cursor, vscode, opencode, codex, zed, windsurf):
npx -y add-mcp github:HenryGetz/unw-mcp -a cursor -n unw \
--env UNW_MCP_TIMEZONE=America/Chicago -yThe first run downloads the source, builds dist/, installs dependencies (~60–90 s with a
cold npm cache), then launches Chromium and completes the SAML/Entra handshake — expect ~90 s
cold on an empty profile. Warm starts answer unw_session op=status in about a second.
Playwright's Chromium binary is not bundled: on a clean machine run
npx playwright install chromium once. npx caches the resolved commit, so after new commits
clear it (npm cache clean --force) to pick them up.
Install from source (for development)
npm install # runs `prepare` → builds dist/
npm run smoke # tools/list over stdio, no browser
npm run live-proof # session + all dashboard/academic/finance ops, read-onlyRegister the local checkout (see mcp.example.json):
{
"mcpServers": {
"unw": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/absolute/path/to/unw-mcp",
"env": { "UNW_MCP_TIMEZONE": "America/Chicago", "UNW_MCP_HEADLESS": "1" }
}
}
}Authentication
The portal is a Pathify/Angular app behind SAML 2.0 with Microsoft Entra ID
(tenant <tenant-id>). There is no API key and no portal bearer token.
Persistent profile:
~/.config/unw-mcp/browser-profile(mode0700).Credentials (only needed when Entra itself expires):
~/.config/unw-mcp/credentials.json(mode0600), falling back to~/.config/teams-mcp/credentials.json. Shape:{ "username", "password", "totpSecret" }(totp_secretis accepted too). Secrets are never copied into this repository.Warm profile:
statusand portal calls reuse thesessionidcookie (30 days, fixed).On
401/403, a redirect to sign-in, or HTML where JSON was expected, the session reloads/dashboardonce. Entra'sESTSAUTHPERSISTENTcookie usually makes this a silent SAML round trip (~7–11 s). If that fails, the server clears only.my.unw.educookies and retries once, then falls back to e-mail + password + TOTP. A rejected password is never retried (lockout protection).All browser work is serialized through one mutex; a cross-process profile lock prevents two MCP instances from sharing the Chromium profile.
Portal and Flow requests use
browserContext.request. Banner origins (registration-ss.oci.unw.edu,student-ss.oci.unw.edu) usepage.evaluate(fetch), because each Banner app owns a separate SAML session.
Banner per-app sessions. Before a Banner read, the server probes the portal session,
navigates that app's registerPostSignIn / studentProfile entry, and if the app returns a
login redirect or HTML it clears only that app's cookies and redoes the SAML handshake once.
A guest JSESSIONID cannot suppress the handshake because the retry clears it. A second
failure becomes auth_required. All Banner requests are GET-only.
Degree audit. The widget catalog carries a 300-second claims JWT. It is re-fetched
before every audit call, passed URL-encoded to Flow, retried once with fresh claims, and
never logged or cached.
Startup and latency
The server does not launch Chromium at startup; the first authenticated tool call does.
On an isolated/cold profile the first call can take ~90 s while the portal session and
Banner app sessions bootstrap. A warm persistent profile answers unw_session status in
about a second and dashboard/academic calls in 0.2–7 s. Call unw_session op=status first if
you want to pay the warm-up explicitly; subsequent questions in the same process reuse the
profile, portal session and in-memory caches.
Configuration
Precedence: environment > ~/.config/unw-mcp/config.yaml > defaults. See
config.example.yaml and .env.example.
Setting | Default | Notes |
|
| all rendering, event windows, today's classes |
|
|
|
| 5 | overview |
| 2 | personalized lists |
| 5 | portal events |
| 10 | dashboard links |
| 10 | portal + Flow profile |
| 10 | terms and registration history |
| 30 | graded-term aggregation |
| 30 | Banner GPA/hours |
| 5 | Banner student data |
| 60 | Banner term list |
| 5 | Flow balances |
| 15 | chapel summary |
| 60 | award + cost bundle |
| 60 | projected 7-day dining dataset |
| 360 | discovered ICS feeds |
| 10 / 1440 | search rows / page bodies |
| 5–20 rows, 300 preview chars, 25 full-dining items/station, 12 full stations, 4,000 page chars | per-call caps; dining brief is fixed at 6 stations × 8 items |
| 60 / 7 | client-side event filter |
Environment overrides: UNW_MCP_CONFIG_DIR, UNW_MCP_PROFILE_DIR, UNW_MCP_TIMEZONE,
UNW_MCP_HEADLESS, UNW_MCP_REQUEST_TIMEOUT_MS, UNW_MCP_NAVIGATION_TIMEOUT_MS,
UNW_MCP_REAUTH_TIMEOUT_MS, and per-cache UNW_MCP_*_TTL_MINUTES (see .env.example).
Token efficiency
Every list request passes an upstream
limit; projections drop internal flags and redundant fields.In-process TTL cache with single-flight loading. Concurrent tool calls do not duplicate requests.
Observed live sizes: dashboard overview 4.3 KB, dashboard day 5.0 KB, announcements 0.37 KB, tasks 1.2 KB, events (10 rows) 2.5 KB, quick links 1.1 KB, academic profile 0.24 KB, today 0.6 KB, schedule 1.7 KB, grades 1.1 KB, GPA 0.3 KB, holds 0.2 KB, registration 0.25 KB, degree audit 1.1 KB, balances 0.12 KB, chapel 0.18 KB, financial aid 5.7 KB, dining locations 1.2 KB, dining today brief 3.4 KB / full 7.0 KB / one meal 1.1 KB, dining week 5.8 KB, academic calendar 1.1 KB, breaks 1.2 KB, deadlines 1.1 KB, page search (10) 2.6 KB, page body 0.55 KB, calendar breaks filtered by query 0.45 KB.
Financial aid and a full dining day are the largest payloads (22 awards + 22 cost rows; ~300 item labels). Both are explicitly capped and never include internal upstream fields.
The dining endpoint is ~1.8 MB; only the projected dataset is cached, and only the requested date/cafe leaves the server. The raw payload is never returned.
Verification
Measured in this repository on 2026-11-17:
Command | Result |
| clean (strict TypeScript, |
| 137 tests / 14 files pass |
| clean |
| 7 tools; all op enums listed; missing/unknown op rejected |
| all seven tools returned live data: session, dashboard, day (3 classes/8 de-duplicated events/3 tasks/1 notice/next meal, 5.0 KB), profile, today, schedule, grades, GPA, holds (1), registration, degree audit (5 degrees; 1/5 has requirement detail), balances (2), chapel (8/20), financial aid (22 awards/22 cost rows), dining brief 3.4 KB vs full 7.0 KB vs one meal 1.1 KB, 7-day week, academic/breaks/deadlines rows, Thanksgiving-filtered breaks (445 B), campus events (10 rows), page search (56 hits, top 10, 2.6 KB), page get |
Unit coverage: config precedence/validation, redaction, sign-in classification, response classification (401 vs SAML HTML vs 5xx vs 302), session status, Banner page fetch plus one-shot re-handshake, TTL/single-flight cache, dashboard projections, Banner term/schedule/ today/grades/GPA/holds/registration projections, degree-audit projection and claims refresh, balance/chapel/aid projections and loaders, dining dataset/day/week/locations projection, brief/full detail, meal filtering and caps, day assembly and next-meal selection, ICS discovery/parsing/cohort merging and date filtering, page HTML→text search/ranking/get, tool schemas and error mapping.
Live proof prints counts, field names and timings only; no names, e-mail addresses, IDs or balances are written to the repository. Live proof is read-only.
Known limitations / not exposed
Time ticket text:
viewRegistrationNoticesreturns an emptytimeTicketsarray for this account. The time ticket lives only in theprepareRegistrationHTML after a term-selection POST; this server does not issue that POST, sotime_ticket_sourceisnot_exposedand standing/allowsRegistration are still returned.Housing assignment/roommates: no endpoint exists in the portal.
Meal-plan swipe counts: only the Dining Funds balance exists.
Degree requirements: Flow returns requirement rows only on the degree record; majors/minors report completion percentages with
requirements_available: falseandrequirements_total: 0. On the live account 4 of 5 programs have no requirement detail; only the degree record does. This is an upstream limitation, not an inference of "complete".Banner pre-registration holds: the JSON
showHoldsendpoint is authoritative; registration-notice holds text is not parsed from HTML.Dining: the public payload covers 7 rolling days only; some cafes (e.g. Heritage) may publish no menu for a date.
todayreportsno_menuper cafe rather than inventing items. Defaultdetail:"brief"caps each station at 8 items and each daypart at 6 stations;detail:"full"uses the configured 12/25 caps. Usemealandcafeto scope further.Academic calendar: discovery depends on the public page embedding Google Calendars. If the layout changes, the tool returns
unavailableinstead of guessed dates. Cohort prefixes (TRAD:,DE:,AGS:) are merged into one row withaudiences.Pages: search covers portal content pages only, not users/directory; results are ranked with exact title/slug matches first and carry
count/truncated. Bodies are capped at 4,000 chars;body_truncated/body_charssay what was cut.
Repository / CI
This repository is public (MIT). It contains no account data, credentials,
browser profiles or raw portal captures; .gitignore excludes node_modules/, dist/, .env*,
config.yaml, credentials.json, browser-profile/, .recon/, artifacts/ and *.tgz.
Everything the server reads from my.unw.edu is read-only — the portal and Banner code
paths issue GETs only (registration is never posted).
ci.yml runs on pushes and pull requests with a read-only GITHUB_TOKEN, no secrets and no
network access to the portal:
npm ci— lockfile install;PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1because unit tests never launch Chromiumnpm run typecheck—tsc --noEmit(strict)npm test—vitest run, mocked HTTP, no browser or credentialsnpm run build— cleandist/
Live checks are operator-only and never run in CI: npm run smoke (tools/list over stdio) and
npm run live-proof (requires a warm authenticated profile on the operator's machine).
Layout
src/
index.ts stdio MCP entrypoint
config.ts YAML + env configuration
cache.ts in-memory TTL + single-flight cache
format.ts, time.ts projection and America/Chicago rendering helpers
auth/
browser.ts persistent Chromium, SAML driver, portal-ready probe
session.ts mutex, portal re-auth, Banner per-app sessions
credentials.ts 0600 credential discovery with teams-mcp fallback
response.ts auth vs availability classification
redact.ts log/URL/token redaction
signin.ts pure Entra page classifier
lock.ts cross-process profile lock
totp.ts RFC 6238
banner/client.ts per-app client; GET-only page fetches
portal/
client.ts origin-locked portal/Flow reader
values.ts tolerant upstream accessors
dashboard.ts dashboard projections + loaders
academics.ts term/schedule/grades/GPA/holds/registration/audit
finances.ts balances, chapel, financial aid
dining.ts public menu dataset + day/week projections
calendar.ts ICS discovery/parsing + campus events
pages.ts page search and slug lookup
tools/ registry, envelopes, four op-dispatched tools
scripts/recon/ reconnaissance behind docs/portal-recon.md
scripts/dev/ smoke and live proof
test/ unit tests (no browser, mock HTTP)
docs/ portal recon, design notes, usage examplesSee SECURITY.md for the threat model and secret handling. See docs/design.md for the
projection/caching design and docs/usage.md for example conversations and payloads.
Available Tools
7 toolsunw_academicsmyUNW academicsA
Academic record: profile/GPA, today's classes, schedule by term, grades by term, official GPA hours, holds, registration standing, and degree audit. Read-only. Times are America/Chicago local; term accepts a Banner code (202610) or name (Fall 2026).
Inputs: op (required), term.
unw_calendarUNW calendarA
Academic calendar and campus events: upcoming semester dates, breaks/recesses, registration and withdrawal deadlines (public Google ICS, cached 6h), plus portal campus events filtered by local date. Read-only.
Inputs: op (required), days, limit, query.
unw_dashboardmyUNW dashboardA
Student dashboard. day is the plan-my-day view: today's classes, next-24h campus events, pending tasks and the next meal with a few options. overview adds identity/degree progress and announcements; announcements/tasks/events/quick_links return one list. Read-only.
Inputs: op (required), days, limit, include_completed.
unw_diningUNW diningA
Campus dining menus: locations, one day's cafes/dayparts/stations/items, or a compact 7-day overview. Public data, cached hourly; never returns the raw menu payload.
Inputs: op (required), cafe, date, meal, +1 more.
unw_financesmyUNW financesB
Student account and dining-funds balances, chapel/spiritual-development credit, and financial-aid awards plus cost of attendance for the active aid year. Read-only; amounts are in USD.
Inputs: op (required), aid_year.
unw_pagesmyUNW pagesA
Search myUNW content pages and read one by slug (registration, meal plans, student accounts, etc.). Bodies are plain text, capped at 4,000 chars with body_truncated/body_chars. Read-only; no directory or user search.
Inputs: op (required), slug, limit, query, +1 more.
unw_sessionmyUNW sessionA
Check the myUNW portal session or force re-authentication. status probes the live API and reports cookie lifetimes; reauth reloads the persistent browser profile (silent SAML ~10s, then credentials+TOTP if Entra expired). No portal data is modified.
Inputs: op (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The core domains (session, academics, finances, dining, calendar, pages) are distinct, but unw_dashboard's 'day' view deliberately re-aggregates data that also lives in unw_academics (today's classes), unw_calendar (campus events), and unw_dining (next meal), so an agent asking about 'today' has several plausible entry points. Descriptions do explain the aggregator role, but the boundaries between dashboard and the domain tools remain blurry in practice.
All seven tools use a uniform 'unw_' prefix followed by a single domain noun, which is predictable and readable. Minor deviation: plurality is inconsistent (academics/finances/pages are plural while session/dashboard/dining/calendar are singular), and the pattern is resource-oriented rather than verb_noun, so actions are only discoverable via descriptions.
Seven tools is well within the sweet spot and each maps to a genuine portal area (auth, dashboard, academics, finances, dining, calendar, pages). No tool feels redundant as a standalone resource, and the surface is compact enough for an agent to hold in context.
The read-only lifecycle is well covered: authentication handling, academic records, balances, dining menus, calendar/deadlines, and content pages. Gaps exist for a student portal — no course/catalog search to support registration, no messages/inbox, and no task creation or completion despite dashboard surfacing pending tasks — but these are workable omissions for a read-only surface.
Maintenance
Related MCP Connectors
Unofficial NTNU course data: search, timetables, grades, course info, and exam logistics.
Search university course materials, your flashcards, quizzes, streak and quota. All tools read-only.
Unofficial Wentworth (WIT) course catalog and student schedule. Needs a WIT sign-in.
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceProvides read-only access to Andrews University's MyAndrews Ellucian portal, enabling retrieval of academic profiles, classes, degree progress, advisors, account balances, tasks, notifications, and portal cards via authenticated browser sessions.-
- AlicenseAqualityBmaintenanceEnables read-only querying of eight campus services through independent local MCP adapters: mailbox search, reading and attachment download, Blackboard courses, academic-system terms, timetable and grades, library loans and navigation, teaching-office notices, the Nan7 market listings, course-review community ratings, and the campus data dashboard. Credentials and sessions remain on the user's own device, encrypted with Windows DPAPI, and nothing is submitted, registered, or booked on the user's behalf.71MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to University of Waterloo accounts across LEARN, WaterlooWorks, Odyssey, Crowdmark, Outline, Piazza, and UW Flow, exposing courses, grades, assignments, announcements, jobs, exam schedules, assessments, outlines, posts, and course info through MCP tools. It also reports sign-in status without submitting, posting, or changing anything.1MIT
- AlicenseAqualityCmaintenanceEnables a tutor or assistant to read a student's Brightspace courses, deadlines, announcements, assignment instructions, course outlines, quiz metadata and released grades, plus search explicitly imported school notes and read course documents. Runs locally over stdio with read-only access and configurable tenant settings.181MIT