Ntnu MCP Server

ntnu-mcp

A remote MCP server that exposes NTNU (Norwegian University of Science and Technology) course data to LLM assistants; course catalog search, teaching schedules, weekly timetables, grade statistics, course descriptions, and exam logistics, plus two comparison tools for students choosing between courses. Runs as a Cloudflare Worker; no installation required on the client side.

Tools

Ten tools, all read-only:

• search_courses — free-text search of NTNU's course catalog for a given year; returns codes, names, campus, and exam dates.
• get_course_schedule — every dated teaching activity (lectures, labs) for a course in a year, with Oslo-local times and rooms.
• get_weekly_timetable — the recurring weekly timetable grid for a course: weekday, times, ISO-week ranges, and rooms.
• get_grade_distribution — historical grade distribution for a course, per year and semester, with counts and percentages.
• get_course_versions — the DBH-versioned course codes (e.g. TDT4100-1) behind a bare course code, useful when grade lookups come back empty.
• get_semesters — NTNU's terms with ids like 26h/26v, teaching weeks, exam-period dates, and which term is current.
• get_course_info — everything about a course except exam logistics: credits, level, campus, prerequisites, mandatory activities, content/learning outcomes, credit reductions, the study programs the teaching is planned for, contacts, and alert notices. English by default, language: "nb" for Norwegian.
• get_exam_info — exam logistics for up to 10 courses in one call: every occasion (ordinary/re-sit) with date, start time, duration, permitted-aids code ("hjelpemiddelkode") with its meaning, exam system, and assigned rooms.
• compare_courses — side-by-side comparison of several courses: name, campus, exam dates, weekly teaching hours, and latest grade distribution.
• check_timetable_conflicts — pairwise check for weekly-schedule clashes and exam-date collisions across a set of courses, before registering for them.

Connecting

Paste the server's MCP URL into Claude's or ChatGPT's custom connector settings:

https://ntnu-mcp.martinsundal.no/mcp

The server requires no authentication, since it only serves public, read-only NTNU course data.

The server is also listed in the official MCP registry as io.github.MartinSA04/ntnu-mcp (see server.json); clients that browse the registry can discover it there. It is an unofficial community server, not affiliated with NTNU. Registry updates are tag-driven: npm version <patch|minor|major> && git push --follow-tags — the version script keeps server.json in sync, and the release workflow runs the check suite, deploys the Worker, re-publishes the registry entry (GitHub OIDC), and creates the GitHub Release.

Architecture

All NTNU upstream knowledge — endpoints, retry policy, parsing of the Liferay catalog, DBH grade statistics, and TP semester data — lives in the ntnu-api TypeScript client library, which this repo depends on as an npm package. Upstream fixes and new data sources land in ntnu-api, not here. This repo's only job is to call that typed client and shape its output for LLM consumption: English names with Norwegian fallback, Oslo-local timestamps, grade rows collapsed into per-term distribution tables, and guidance notes on empty results. This layering is set out in ntnu-api's TypeScript migration spec.

To keep load on NTNU's servers minimal, every upstream call is cached in two tiers (per-isolate memory in front of a shared Workers KV namespace), so each resource is fetched roughly once per TTL globally: catalog searches, timetables, and schedules for 1 hour; grade statistics and the semester list for 24 hours. KV failures degrade to memory-only caching, never to tool errors. In tests the cache runs memory-only.

Local development

Requires Node 22 (pinned via mise).

mise install     # installs the pinned Node version
npm install

Common tasks, available both as mise tasks and npm scripts:

mise run dev          # npm run dev       — wrangler dev, local worker with hot reload
mise run test          # npm test          — vitest, over captured fixtures (no live network)
mise run typecheck     # npm run typecheck — tsc --noEmit
mise run lint          # npm run lint      — biome check
mise run fmt           # npm run fmt       — biome check --write
mise run check         # lint + typecheck + test

Tests run under plain Node (not the Workers pool) with vitest, driving the tool functions directly against fetch fixtures captured verbatim from ntnu-api's test suite — no calls to real NTNU services are made in CI or locally.

Deploy

Pushes to main deploy automatically (the repo is connected to Cloudflare Workers Builds). For a manual deploy from a checkout:

npm run deploy   # wrangler deploy

Runs on Cloudflare's free plan: the MCP session state is backed by a Durable Object using SQLite storage, which is available on the free tier (no Workers Paid subscription required unless per-request CPU limits are hit at scale).

License

MIT — see LICENSE.