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

¹ Either CALDAV_USERNAME + CALDAV_PASSWORD, or CALDAV_TOKEN.

Booleans are compared against the literal string true where the switch lifts a protection (CALDAV_INSECURE_TLS, CALDAV_ALLOW_PLAINTEXT), and read tolerantly — 1, yes, TRUE — where it turns one on (CALDAV_READ_ONLY). A typo should never quietly remove a guard.

The server starts without credentials on purpose, so a registry or a sandbox inspector can list its tools; every call then fails with setup instructions.

Choosing which tools load

Twenty-two tools is a lot of context on every request, and a model picks worse from a long list than from a short one.

CALDAV_ALLOW_TOOLS=essential                       # a curated seven
CALDAV_ALLOW_TOOLS=list_events,get_event,create_event
CALDAV_ALLOW_TOOLS=list_*                          # one trailing * only
CALDAV_DENY_TOOLS=delete_event                     # subtracted from the above