ni-c/caldav-mcp

A Model Context Protocol (MCP) server for
CalDAV, the open calendar
standard behind Nextcloud, Radicale, Baikal, SOGo, Fastmail, mailbox.org and
iCloud.
Lets MCP clients like Claude Code, Claude Desktop or Codex work with your
calendar: see what is on, find a free slot, create and change events, keep tasks
and dated notes, and answer an invitation — against your own server, with no
vendor API in between.
Twenty-two tools is the ceiling, not the floor: CALDAV_ALLOW_TOOLS=essential
registers a curated seven instead, and a model picks the right tool far more
reliably from seven than from twenty-two — see
choosing which tools load.
What makes it different
**Recurring entries are expanded here, not asked of the server.** A weekly
meeting is stored as one rule plus a handful of exceptions; this server turns
that into individual occurrences, each with an id of its own, so one of them can
be moved without touching the rest. RFC 4791 does offer server-side expansion —
but support for it is uneven and its absence is _silent_: a server that ignores
the request answers with the master component, so the result looks thin rather
than wrong. Doing it here behaves the same everywhere, and it means a 09:00
meeting stays at 09:00 across a daylight-saving change.
**Times carry their zone, not just an offset.** Every timestamp comes back three
ways at once: the instant with an explicit offset, the IANA zone the entry was
written in, and a flag for whole-day entries. Only the zone survives a
daylight-saving change — an event pinned to +02:00 moves an hour every winter —
and a whole-day entry reported as midnight is how a public holiday shows up as a
one-minute appointment.
**Writing reads first, and never rebuilds.** A CalDAV PUT replaces the entire
resource, so every change here is applied to the entry _as stored_. The
properties this server does not model — attendees, attachments, reminders it
cannot write, whatever a vendor added — survive because they are never touched,
not because anything preserves them. Every write carries the entry's ETag, so a
change somebody made in the meantime is reported instead of overwritten, and an
entry too large to read in full is refused rather than written from a truncated
read.
**Calendar content is treated as somebody else's writing.** On a server with
scheduling enabled, anyone who knows your address can put an entry in your
calendar without you accepting it. Summaries, descriptions, locations and
organiser names are therefore marked as untrusted data, stripped of the
characters a reader cannot see, and — for a single entry — fenced inside a
delimiter the entry itself cannot forge.
Requirements
- Node.js 22 or newer, or Docker
- A CalDAV server and an account on it
Most hosted services want an **app-specific password** rather than the account
password: Nextcloud, Fastmail and iCloud all issue one per application. Google
Calendar is not supported — it requires OAuth and has deprecated password
authentication for CalDAV.
Tested against Radicale and Baikal (sabre/dav) in CI on every pull request.
Configuration
| Variable | Required | Description |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CALDAV_URL | yes | Root of the CalDAV server, e.g. https://dav.example.net. A calendar collection URL works too and limits the server to that one calendar. |
| CALDAV_USERNAME | yes¹ | Account name. |
| CALDAV_PASSWORD | yes¹ | Password or app-specific password. Deleted from the environment once read. |
| CALDAV_TOKEN | yes¹ | Bearer token instead of username and password. Not both. |
| CALDAV_CALENDARS | no | Comma-separated calendars this server may touch, by path or final path segment. Default: every calendar the account can see. |