{
  "markdown": "# ntnu-mcp\n\nA remote [MCP](https://modelcontextprotocol.io) server that exposes NTNU\n(Norwegian University of Science and Technology) course data to LLM assistants; course catalog search, teaching schedules, weekly timetables, grade\nstatistics, course descriptions, exam logistics, and study programs with\ntheir official study plans, plus comparison tools for students choosing\nbetween courses.\nRuns as a Cloudflare Worker; no installation required on the client side.\n\n## Tools\n\nTwelve tools, all read-only:\n\n- **`search_courses`** — free-text search of NTNU's course catalog for a given year; returns codes, names, campus, and exam dates.\n- **`get_course_schedule`** — every dated teaching activity (lectures, labs) for a course in a year, with Oslo-local times and rooms.\n- **`get_weekly_timetable`** — the recurring weekly timetable grid for a course: weekday, times, ISO-week ranges, and rooms.\n- **`get_grade_distribution`** — historical grade distribution for a course, per year and semester, with counts and percentages.\n- **`get_course_versions`** — the DBH-versioned course codes (e.g. `TDT4100-1`) behind a bare course code, useful when grade lookups come back empty.\n- **`get_semesters`** — NTNU's terms with ids like `26h`/`26v`, teaching weeks, exam-period dates, and which term is current.\n- **`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.\n- **`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.\n- **`search_study_programs`** — search NTNU's ~400 study programs by text, level, and city; returns program codes for `get_study_plan`.\n- **`get_study_plan`** — the official plan for a program and cohort intake year: courses (codes, credits, mandatory/elective) per semester, with specialization choice points — the bridge from \"I study X\" to concrete course codes.\n- **`compare_courses`** — side-by-side comparison of several courses: name, campus, exam dates, weekly teaching hours, and latest grade distribution.\n- **`check_timetable_conflicts`** — pairwise check for weekly-schedule clashes and exam-date collisions across a set of courses, before registering for them.\n\n## Connecting\n\nPaste the server's MCP URL into Claude's or ChatGPT's custom connector\nsettings:\n\n```\nhttps://ntnu-mcp.martinsundal.no/mcp\n```\n\nThe server requires no authentication, since it only serves public,\nread-only NTNU course data.\n\nThe server is also listed in the\n[official MCP registry](https://registry.modelcontextprotocol.io) as\n`io.github.MartinSA04/ntnu-mcp` (see [server.json](server.json)); clients\nthat browse the registry can discover it there. It is an unofficial\ncommunity server, not affiliated with NTNU. Registry updates are\ntag-driven: `npm version <patch|minor|major> && git push --follow-tags` —\nthe `version` script keeps `server.json` in sync, and the\n[release workflow](.github/workflows/release.yml) runs the check suite,\ndeploys the Worker, re-publishes the registry entry (GitHub OIDC), and\ncreates the GitHub Release.\n\n## Architecture\n\nAll NTNU upstream knowledge — endpoints, retry policy, parsing of the\nLiferay catalog, DBH grade statistics, and TP semester data — lives in the\n[`ntnu-api`](https://github.com/MartinSA04/ntnu-api) TypeScript client\nlibrary, which this repo depends on as an npm package. **Upstream fixes and\nnew data sources land in `ntnu-api`, not here.** This repo's only job is to\ncall that typed client and shape its output for LLM consumption: English\nnames with Norwegian fallback, Oslo-local timestamps, grade rows collapsed\ninto per-term distribution tables, and guidance notes on empty results. This\nlayering is set out in `ntnu-api`'s\n[TypeScript migration spec](https://github.com/MartinSA04/ntnu-api/blob/main/docs/ts-migration-spec.md).\n\nTo keep load on NTNU's servers minimal, every upstream call is cached in two\ntiers (per-isolate memory in front of a shared Workers KV namespace), so each\nresource is fetched roughly once per TTL globally: catalog searches,\ntimetables, and schedules for 1 hour; grade statistics and the semester list\nfor 24 hours. KV failures degrade to memory-only caching, never to tool\nerrors. In tests the cache runs memory-only.\n\n## Local development\n\nRequires Node 22 (pinned via [mise](https://mise.jdx.dev/)).\n\n```sh\nmise install     # installs the pinned Node version\nnpm install\n```\n\nCommon tasks, available both as mise tasks and npm scripts:\n\n```sh\nmise run dev          # npm run dev       — wrangler dev, local worker with hot reload\nmise run test          # npm test          — vitest, over captured fixtures (no live network)\nmise run typecheck     # npm run typecheck — tsc --noEmit\nmise run lint          # npm run lint      — biome check\nmise run fmt           # npm run fmt       — biome check --write\nmise run check         # lint + typecheck + test\n```\n\nTests run under plain Node (not the Workers pool) with vitest, driving the\ntool functions directly against fetch fixtures captured verbatim from\n`ntnu-api`'s test suite — no calls to real NTNU services are made in CI or\nlocally.\n\n## Deploy\n\nPushes to `main` deploy automatically (the repo is connected to Cloudflare\nWorkers Builds). For a manual deploy from a checkout:\n\n```sh\nnpm run deploy   # wrangler deploy\n```\n\nRuns on Cloudflare's free plan: the MCP session state is backed by a Durable\nObject using SQLite storage, which is available on the free tier (no Workers\nPaid subscription required unless per-request CPU limits are hit at scale).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 5877,
  "sha": "5a4421c2e580ebeaafb0c51e14dafaf589ab01e634ee94fcff5cdb337f77c9be",
  "repo_slug": "martinsa04/ntnu-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_martinsa04_ntnu_mcp_c9da8d54/readme"
}