DTU Calendar MCP

A local MCP server for DTU Learn calendar feeds. It lets an AI client read classes, assignments, deadlines, exams, and recent calendar changes without browser automation.

The server only reads DTU. It writes fetched events to a local SQLite cache so queries stay fast and still work when Learn is temporarily unavailable.

What it can answer

• What is on my DTU calendar this week?

• Which assignments or peer-feedback deadlines are coming up?

• What does Learn show for course 12345?

• Did an event move, change, or disappear?

• Is the feed configured, current, or stale?

The MCP server provides six tools:

• list_upcoming

• list_deadlines

• get_calendar_item

• get_course_overview

• get_calendar_changes

• get_feed_status

Calendar data does not prove course registration, exam registration, completion, grades, or passed ECTS.

Related MCP server: waterloo-learn-mcp

Requirements

• Python 3.11 or newer

• A private DTU Learn iCalendar subscription URL

• An MCP client that can run a local stdio server

Install

Clone the repository, then open a terminal in it.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
dtu-calendar-mcp --version

On macOS or Linux, activate the environment with source .venv/bin/activate.

Add your DTU Learn feed

The subscription URL is a bearer secret. Anyone with the URL may be able to read your calendar. Do not commit it, paste it into an issue, or put it in MCP JSON.

Get the calendar URL:

1. Open DTU Learn.

2. Go to Calendar.

3. Choose Subscribe.

4. Copy the full subscription URL.

Get the tasks URL:

1. Open Calendar in DTU Learn.

2. Go to Tasks.

3. Choose Subscribe.

4. Copy the full tasks subscription URL.

Create a .env file in the repository root. Git ignores this file.

DTU_LEARN_ICS_URL=<paste the full calendar subscription URL>
DTU_LEARN_TASKS_ICS_URL=<paste the full tasks subscription URL>

Paste the whole URL, not only the value after token=. The tasks feed is optional.

Check the configuration:

dtu-calendar-mcp doctor
dtu-calendar-mcp sync

Real environment variables take precedence over .env values. This is useful if your MCP client has its own secret store.

If a feed URL has been exposed, revoke or regenerate it in DTU Learn before using this project.

See configuration.md for persistent environment settings, timezone options, and cache location.

Connect an MCP client

Use this server definition in a client that inherits the environment containing your feed URL:

{
  "mcpServers": {
    "dtu-calendar": {
      "command": "dtu-calendar-mcp",
      "args": ["serve"]
    }
  }
}

The repository also contains a Codex plugin under plugins/dtu-calendar-mcp. The plugin contains no feed URL or personal data.

How refreshes work

The list, item, and course tools refresh stale feeds before reading. A refresh contacts the configured DTU URL and updates the local cache. Change and status queries only read the cache.

Every result includes data_as_of, stale, warnings, and configured_sources. Check them before treating an empty result as proof that nothing is scheduled. If a feed suddenly becomes empty or loses more than half its events, the server keeps the previous snapshot and marks the refresh as suspect.

The default cache is %LOCALAPPDATA%\dtu-calendar-mcp\calendar.sqlite3 on Windows and ~/.cache/dtu-calendar-mcp/calendar.sqlite3 elsewhere.

Limits

The parser supports the recurrence patterns normally used by calendar feeds, including daily, weekly, monthly, exclusions, added dates, and individual occurrence changes. It bounds feed size, event text, recurrence expansion, and MCP output so one bad item cannot fill the disk or hang the server.

Read limits.md for exact behavior and privacy.md before connecting an institutional feed to a model provider.

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check .
powershell -ExecutionPolicy Bypass -File .\scripts\check-release.ps1

The test suite uses synthetic calendar data. Do not add real student feeds or subscription tokens to fixtures.

License

MIT. See LICENSE.