What it does

tudelft-mcp is an MCP server that runs on your own machine and gives Claude, ChatGPT, Codex, Cursor, VS Code, Windsurf, Zed, Gemini CLI or any other MCP client access to your Brightspace courses, your official OSIRIS records on my.tudelft.nl, your MyTimetable schedule and the public Study Guide. You sign in once in a browser window; after that the session renews itself. Write actions (submitting an assignment, joining a group, replying in a discussion, registering for a course or exam) always show a preview first and only go through after you confirm.

Things you can ask once it is connected:

• What is due this week across my courses?
• Summarise the lecture slides for week 3 of EE4109.
• What changed in my courses since yesterday?
• Show my official OSIRIS grades and my weighted average.
• What is my timetable for tomorrow, and where are the rooms?
• Find the section about Nyquist stability in my course materials.

Install

macOS and Linux:

curl -fsSL https://danieltyukov.github.io/tudelft-mcp/install.sh | sh

Windows (PowerShell):

irm https://danieltyukov.github.io/tudelft-mcp/install.ps1 | iex

With npm on any platform:

npm install -g tudelft-mcp && tudelft-mcp setup

Then sign in once:

tudelft-mcp login

A browser window opens on the university login page. Finish the sign-in there, including MFA. Brightspace, OSIRIS and MyTimetable connect in that same window and the window closes when it is done.

Connect a client

tudelft-mcp setup detects the MCP clients installed on your machine and writes their config. Supported: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex, Gemini CLI and Cline. Use --dry-run to see what it would write, or name the clients to configure, for example tudelft-mcp setup cursor. Details per client are in docs/clients.md.

To run it without a global install, sign in with npx -y tudelft-mcp login and point the client at npx:

{
  "mcpServers": {
    "tudelft": {
      "command": "npx",
      "args": ["-y", "tudelft-mcp", "serve"]
    }
  }
}

tudelft-mcp setup --command npx writes this entry for you.

ChatGPT connects over HTTP instead of stdio:

tudelft-mcp serve --http --tunnel

This prints a public URL and a bearer token to paste into ChatGPT's connector settings. Desktop clients can stay connected at the same time.

Requirements

• Node 20 or newer.
• Google Chrome, Microsoft Edge, Chromium or Brave. Without any of them, run tudelft-mcp browser install to download a Chromium build.
• A TU Delft account.

Tools

| Area | Tools | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Sign-in | auth_status, auth_login, auth_logout | | Courses and materials | list_courses, get_course_content, read_material, sync_course, search_materials, whats_new, search_catalog | | Announcements and assignments | get_announcements, list_assignments, read_assignment_attachment, prepare_submission, confirm_submission | | Grades and planning | get_grades, get_grade_summary, get_upcoming, get_calendar, exam_overview | | OSIRIS | osiris_grades, osiris_progress, osiris_registrations, osiris_search_courses, osiris_prepare_registration | | Timetable | get_timetable, timetable_status, connect_timetable | | Study Guide and campus | search_study_guide, get_study_guide, search_rooms, search_study_spaces, get_ict_notices | | Discussions and groups | read_discussions, prepare_discussion_post, get_groups, prepare_group_join, list_locker_files |

The full list with input fields and annotations is generated into docs/tools.md by npm run docs:tools.

How sign-in works

tudelft-mcp login opens one window of your own browser on the Brightspace login page, waits for you to finish the university sign-in, and then connects OSIRIS and MyTimetable in the same window without asking again. The browser profile is kept under ~/.tudelft-mcp/profile, so the university session cookies survive restarts. When an API call is rejected, the server opens that profile headless, lets the single sign-on complete without a window, and captures fresh tokens; this works for as long as the university session itself is valid. When the university asks for a password or MFA again, tools return AUTH_REQUIRED and you run tudelft-mcp login once more.

Privacy

Everything runs locally; there is no hosted backend. Cookies, tokens and the calendar feed URL are stored under ~/.tudelft-mcp with owner-only permissions (wrapped with DPAPI on Windows) and are never returned to the model. Query strings that look like credentials are stripped from every link a tool returns. Your password and MFA are typed only in the university's own pages. tudelft-mcp logout removes the saved sessions and the browser profile.

Development

npm ci
npm run check          # typecheck, lint, tests, build
npm run dev -- status  # run the CLI from source

Unit tests use fixtures and a mocked fetch. Tests under tests/live/ talk to the real services from a signed-in machine and only run with TUDELFT_LIVE=1; they never run in CI.

Contributing

See CONTRIBUTING.md for the setup, how to add a tool, and the rules for fixtures. Security issues go through SECURITY.md.

License

MIT. See LICENSE.

Not affiliated with TU Delft.