CalDAV MCP Server
CalDAV MCP Server
CalDAV MCP Server ist ein Model Context Protocol Server zur Verwaltung von iCloud-Kalenderereignissen, einschließlich nativer Unterstützung für mehrere VALARM-Erinnerungen an einem Ereignis.
iCloud-Kalender ist der einzige Anbieter, der in der ersten Version offiziell unterstützt und manuell validiert wird. Der Server funktioniert mit jedem MCP-Client, der stdio oder Streamable HTTP unterstützt.
Dieses unabhängige Projekt ist nicht mit Apple Inc. verbunden, von ihr autorisiert, gesponsert oder genehmigt. Apple und iCloud sind Marken ihrer jeweiligen Eigentümer.
Navigation
Related MCP server: DAV MCP Server
Über
Der Server verbindet ein konfiguriertes Konto über CalDAV mit iCloud. Er erkennt die Kalender des Kontos und stellt normalisierte Lese- und Schreiboperationen über MCP bereit.
Updates bewahren die vollständige iCalendar-Ressource, einschließlich unbekannter Eigenschaften, Apple-Erweiterungen, VTIMEZONE, Ausnahmen bei Serien und Alarme, die in einem Patch ausgelassen wurden. Schreibvorgänge verwenden undurchsichtige Ressourcen-IDs und ETags, anstatt anzunehmen, dass ein CalDAV-Dateiname mit einer Ereignis-UID übereinstimmt.
Kalenderressourcen werden im Speicher verarbeitet. Der Server hat keine Telemetrie und keine Anwendungsdatenbank, und rohes iCalendar wird nur auf ausdrückliche Anfrage zurückgegeben.
Funktionen
Erkennt Kalender, die für das konfigurierte iCloud-Konto verfügbar sind.
Listet Ereignisse in halboffenen Zeiträumen auf und expandiert wiederkehrende Vorkommen.
Erstellt terminierte, ganztägige und wiederkehrende Ereignisse.
Unterstützt null, ein oder mehrere Anzeigealarme pro Ereignis.
Gibt die Apple-Alarmerweiterungen aus, die von iCloud-Kalender erwartet werden.
Liest Ereignisse über undurchsichtige Ressourcen-ID oder über Kalender-ID und UID.
Wendet Teilaktualisierungen an, während ausgelassene und unbekannte iCalendar-Daten erhalten bleiben.
Verwendet ETags für optimistische Nebenläufigkeit bei Aktualisierungen und Löschungen.
Lehnt isolierte Änderungen an Serienvorkommen ab, anstatt die gesamte Serie zu ändern.
Schwärzt Anmeldedaten, rohen Kalenderinhalt und CalDAV-Pfade aus Protokollen und Fehlern.
Läuft als Nicht-Root-Container mit einer schreibgeschützten Root-Dateisystemkonfiguration.
Unterstützt
stdio- und Streamable-HTTP-MCP-Transports.
MCP-Tools
list_calendars
Listet die für das konfigurierte Konto erkannten Kalender auf. Jedes Ergebnis enthält eine undurchsichtige calendar_id, Anzeigename, Beschreibung, Zeitzone und einen Best-Effort-Schreibstatus.
list_events
Listet Ereignisse in einem halboffenen Intervall auf und expandiert wiederkehrende Vorkommen. Der maximale Bereich beträgt 366 Tage, die Standardseitengröße ist 100, und die maximale Seitengröße ist 500. Ergebnisse verwenden eine deterministische chronologische Reihenfolge. Paginierungscursor sind undurchsichtig und stellen keinen Snapshot dar, wenn Ereignisse während der Durchquerung geändert werden.
Beispieleingabe:
{
"calendar_id": "opaque-calendar-id",
"start": "2026-09-01T00:00:00Z",
"end": "2026-10-01T00:00:00Z",
"timezone": "Europe/Berlin",
"limit": 100
}get_event
Liest ein Ereignis über resource_id oder über ein Paar aus calendar_id und UID. Rohes iCalendar ist standardmäßig ausgeschlossen und kann mit include_raw_ical: true für kontrollierte Diagnosen angefordert werden.
create_event
Erstellt ein Ereignis und liest die vom Server gespeicherte Darstellung zurück.
Terminiertes Ereignis mit zwei Alarmen:
{
"calendar_id": "opaque-calendar-id",
"summary": "Buy Shinkansen tickets",
"start": {
"date_time": "2026-09-06T03:00:00+02:00",
"timezone": "Europe/Berlin"
},
"end": {
"date_time": "2026-09-06T03:30:00+02:00",
"timezone": "Europe/Berlin"
},
"description": "Smart-EX",
"location": null,
"alarms": [
{ "minutes_before": 1440, "action": "DISPLAY" },
{ "minutes_before": 0, "action": "DISPLAY" }
],
"rrule": null
}Ganztägiges Ereignis mit einem exklusiven Enddatum:
{
"calendar_id": "opaque-calendar-id",
"summary": "Trip",
"start": { "date": "2026-09-06" },
"end": { "date": "2026-09-08" },
"alarms": []
}Wiederkehrende Ereignisse akzeptieren eine RFC-5545-Regel ohne das Präfix RRULE::
{
"calendar_id": "opaque-calendar-id",
"summary": "Weekly planning",
"start": {
"date_time": "2026-09-07T09:00:00+02:00",
"timezone": "Europe/Berlin"
},
"end": {
"date_time": "2026-09-07T09:30:00+02:00",
"timezone": "Europe/Berlin"
},
"rrule": "FREQ=WEEKLY;BYDAY=MO;COUNT=10"
}update_event
Patched ein Ereignis oder eine vollständige wiederkehrende Serie. Ausgelassene Felder bleiben erhalten, null entfernt ein nullable Feld, und alarms: [] entfernt alle Alarme. Ein optionales expected_etag verhindert das Überschreiben einer neueren Serverversion.
delete_event
Löscht ein Ereignis oder eine vollständige wiederkehrende Serie, optional mit einem beobachteten ETag. Das Löschen eines einzelnen expandierten Vorkommens wird in der aktuellen Version nicht unterstützt.
Technologie-Stack
TypeScript mit strengen Projektregeln
Installation
Voraussetzungen
Ein iCloud-Konto mit aktiviertem Kalender.
Zwei-Faktor-Authentifizierung für das Apple-Konto aktiviert.
Docker und Docker Compose für die Containerbereitstellung oder Node.js 24+ und pnpm für eine lokale Installation.
Docker Compose
Die empfohlene Installation verwendet das veröffentlichte Multi-Architektur-Image:
ghcr.io/lukegskw/caldav-mcp:latestLaden Sie das Compose-Beispiel herunter:
curl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yamlGeben Sie die Apple-Konto-E-Mail und das App-spezifische Passwort an und starten Sie dann den Dienst:
export CALDAV_USERNAME='user@example.com'
export CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx'
docker compose -f compose.example.yaml up -dUm einen anderen Host-Port zu veröffentlichen, setzen Sie:
export CALDAV_MCP_PUBLISHED_PORT=18100
docker compose -f compose.example.yaml up -dDas latest-Tag folgt dem neuesten erfolgreichen Build aus dem Standard-Branch. Für eine kontrollierte Bereitstellung oder ein Rollback ersetzen Sie es in der Compose-Datei durch eine veröffentlichte Version oder ein unveränderliches sha-*-Tag.
Der Streamable-HTTP-Endpunkt ist verfügbar unter:
http://<host>:8100/mcpDer Host-Port kann sich ändern, ohne Port 8100 im Container zu ändern. Es ist kein persistentes Volume erforderlich; Kalenderdaten bleiben in iCloud.
Docker run
Die gleiche gehärtete Container-Konfiguration kann direkt gestartet werden:
docker run -d \
--name caldav-mcp \
--restart unless-stopped \
--read-only \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--tmpfs /tmp:size=16m,mode=1777 \
-e CALDAV_PROVIDER=icloud \
-e CALDAV_USERNAME \
-e CALDAV_PASSWORD \
-e CALDAV_MCP_TRANSPORT=streamable-http \
-e CALDAV_MCP_HOST=0.0.0.0 \
-p 8100:8100 \
ghcr.io/lukegskw/caldav-mcp:latestContainer aus dem Quellcode erstellen
Das lokale Erstellen ist optional. Bevorzugen Sie das veröffentlichte Image, es sei denn, Sie müssen den Container-Build ändern oder prüfen.
git clone https://github.com/lukegskw/caldav-mcp.git
cd caldav-mcp
docker buildx build --load -t caldav-mcp:local .Lokale Node.js-Installation
git clone https://github.com/lukegskw/caldav-mcp.git
cd caldav-mcp
pnpm install --frozen-lockfile
cp .env.example .env
pnpm build
pnpm start -- --transport stdioIm stdio-Modus ist stdout ausschließlich für MCP-Nachrichten reserviert. Um Streamable HTTP lokal auszuführen:
CALDAV_MCP_TRANSPORT=streamable-http pnpm startKonfiguration
Alle Einstellungen verwenden das Präfix CALDAV_ oder CALDAV_MCP_.
Variable | Erforderlich | Standard | Beschreibung |
| Nein |
| Anbieterrichtlinie. iCloud ist das unterstützte Profil. |
| Nein |
| CalDAV-Erkennungs-URL. |
| Ja | Keine | Apple-Konto-E-Mail. |
| Ja | Keine | App-spezifisches Passwort, nicht das Kontopasswort. |
| Nein |
|
|
| Nein |
| HTTP-Bind-Adresse. |
| Nein |
| HTTP-Listening-Port. |
| Nein |
| Anwendungsprotokollstufe. |
| Nein |
| CalDAV-Anfrage-Timeout. |
Der Kern behält eine experimentelle generic-Anbieterrichtlinie und eine konfigurierbare URL bei, um Apple-Erweiterungen von der gemeinsamen iCalendar-Implementierung zu isolieren. Derzeit wird keine Kompatibilität mit anderen Anbietern beansprucht.
Geheimnisse müssen über die Bereitstellungsplattform oder die Umgebung bereitgestellt werden. Committen Sie niemals .env, übergeben Sie Anmeldedaten nicht als MCP-Tool-Argumente und nehmen Sie sie nicht in Diagnoseberichte auf.
MCP-Client-Einrichtung
Für jeden MCP-Client, der Streamable-HTTP-Serverdefinitionen akzeptiert, konfigurieren Sie die URL:
mcp_servers:
caldav:
url: http://<host>:8100/mcpWenn der Client das Compose-Netzwerk teilt, verwenden Sie den Dienstnamen und den internen Port:
mcp_servers:
caldav:
url: http://caldav-mcp:8100/mcpFür Clients, die lokale stdio-Server starten, konfigurieren Sie den Befehl, um node /absolute/path/to/caldav-mcp/dist/main.js mit den erforderlichen Umgebungsvariablen auszuführen.
Claude Desktop (Docker, stdio)
Claude Desktop startet lokale stdio-Server als Unterprozesse. Das Ausführen des veröffentlichten Containers auf diese Weise hält das App-spezifische Passwort auf dem Client-Computer und öffnet keinen Netzwerkport, was den Transportrichtlinien in Einschränkungen entspricht.
Fügen Sie den Server zu claude_desktop_config.json hinzu:
{
"mcpServers": {
"icloud-calendar": {
"command": "/absolute/path/to/docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
"/absolute/path/to/caldav-mcp.env",
"-e",
"CALDAV_PROVIDER=icloud",
"-e",
"CALDAV_MCP_TRANSPORT=stdio",
"ghcr.io/lukegskw/caldav-mcp@sha256:<digest>"
]
}
}
}-i ist erforderlich. Ohne angehängtes stdin kann der Client nicht mit dem Container über MCP kommunizieren. --rm entfernt den Container, sobald der Client ihn stoppt.
Stellen Sie Anmeldedaten über --env-file bereit, nicht über -e. Argumente, die an docker run übergeben werden, sind im Host-Prozessverzeichnis sichtbar; der Inhalt einer Env-Datei ist es nicht. Die Datei enthält die in Konfiguration beschriebenen Variablen:
CALDAV_USERNAME=user@example.com
CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxxPinnen Sie das Image per Digest anstelle von latest, damit ein Neustart des Clients nicht stillschweigend eine andere Version startet:
docker pull ghcr.io/lukegskw/caldav-mcp:latest
docker images --digests ghcr.io/lukegskw/caldav-mcpStarten Sie Claude Desktop nach dem Bearbeiten der Konfigurationsdatei vollständig neu.
Windows
Erstellen und finden Sie die Konfigurationsdatei über Einstellungen -> Entwickler -> Konfiguration bearbeiten. Gehen Sie nicht von einem Pfad aus. Wenn Claude Desktop aus dem Microsoft Store installiert ist, leitet Windows %APPDATA%\Claude in den Paketcontainer um, und die Datei befindet sich unter:
%LOCALAPPDATA%\Packages\Claude_<package-id>\LocalCache\Roaming\Claude\claude_desktop_config.jsonIn diesem Fall meldet dir %APPDATA%\Claude nichts. Serverprotokolle werden neben der Konfigurationsdatei in logs\mcp-server-<server-name>.log geschrieben.
Verwenden Sie den absoluten Pfad zu docker.exe, da PATH im Paketcontainer nicht zuverlässig ist. where docker gibt ihn aus, typischerweise C:\Program Files\Docker\Docker\resources\bin\docker.exe. Backslashes müssen in JSON maskiert werden.
Die Konfigurationsformate unterscheiden sich zwischen MCP-Clients. Konsultieren Sie die Dokumentation des Clients für das genaue Schema und laden Sie es neu oder starten Sie es neu, nachdem Sie die Serverdefinition geändert haben.
Verifizierung
Überprüfen Sie den Containerstatus und die Protokolle:
docker compose -f compose.example.yaml ps
docker compose -f compose.example.yaml logs caldav-mcpDer Container sollte healthy melden. Der TCP-Healthcheck validiert den Serverprozess, nicht die iCloud-Anmeldedaten.
Führen Sie die Repository-Verifizierungssuite aus:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm buildVerbinden Sie sich schließlich mit einem MCP-Client und bestätigen Sie, dass alle sechs Tools aufgelistet sind. Vor einer Veröffentlichung führen Sie die dedizierte iCloud-Manualvalidierung gegen einen Testkalender durch.
Einschränkungen
Pro Serverprozess oder Container ist ein iCloud-Konto konfiguriert.
Der Streamable-HTTP-Endpunkt hat in der aktuellen Version keine Authentifizierung. Beschränken Sie ihn auf ein vertrauenswürdiges LAN, VPN oder privates Containernetzwerk; setzen Sie ihn nicht direkt dem Internet aus.
Einzelne Serienvorkommen sind schreibgeschützt. Das Aktualisieren oder Löschen der vollständigen Serie wird unterstützt.
Es werden nur
ACTION:DISPLAY-Alarme erstellt.Einzelne iCalendar-Ressourcen sind auf 5 MiB begrenzt.
Ereignislistenbereiche sind auf 366 Tage und Seiten auf 500 Ergebnisse begrenzt.
Ereignisse dürfen höchstens 20 Alarme enthalten.
Teilnehmerscheduling liegt außerhalb des aktuellen Umfangs.
Andere Anbieter als iCloud werden nicht offiziell unterstützt.
Siehe Fehlerbehebung für Hinweise zu Erkennung, Authentifizierung, ETag und Apple-Erweiterungen. Lesen Sie SECURITY.md, bevor Sie ein Sicherheitsproblem melden oder Diagnosen anhängen.
Mitwirken
Beiträge sind willkommen. Bevor Sie einen Pull-Request öffnen:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t caldav-mcp:test .Änderungen an CalDAV-Schreibvorgängen oder iCalendar-Serialisierung müssen ETag-Prüfungen, undurchsichtige Ressourcengrenzen, unbekannte Eigenschaften, Serienausnahmen und in Patches ausgelassene Alarme bewahren. TypeScript-Änderungen müssen weiterhin die Regeln in .codex/rules/typescript.md erfüllen.
Lizenz
MIT. Siehe LICENSE.
Available Tools
6 toolscreate_eventCreate calendar eventA
Create a new event in a writable iCloud calendar and return the stored representation; existing events are not changed. Use list_calendars first to obtain calendar_id, and use update_event when the event already exists. Timed values require matching offsets and timezones, all-day end dates are exclusive, recurrence rules omit the RRULE: prefix, and travel_minutes sets Apple Calendar travel time for timed events.
Inputs: end (required), start (required), summary (required), calendar_id (required), +5 more. Returns: end, uid, etag, href, +13 more
delete_eventDelete calendar eventADestructiveIdempotent
Permanently delete an event or entire recurring series; individual expanded occurrences are not supported. Target it by resource_id or by calendar_id with uid, and supply expected_etag when available to prevent deleting a concurrently changed event.
Inputs: uid, calendar_id, resource_id, expected_etag. Returns: deleted, resource_id
get_eventGet calendar eventARead-onlyIdempotent
Read one event by resource_id, preferably from a previous result, or by the calendar_id and uid pair. Use list_events for range searches. Request raw iCalendar only for controlled diagnostics because it may contain sensitive calendar data.
Inputs: uid, calendar_id, resource_id, include_raw_ical. Returns: end, uid, etag, href, +13 more
list_calendarsList calendarsARead-onlyIdempotent
List calendars available in the configured iCloud account. Use this first to obtain the opaque calendar_id required by list_events and create_event; writable is a best-effort capability indicator.
Inputs: no named parameters. Returns: calendars
list_eventsList calendar eventsARead-onlyIdempotent
List events that overlap the start-inclusive, end-exclusive interval and expand recurring series into occurrences, across at most 366 days. Use list_calendars first to obtain calendar_id and use get_event instead for one known event. Continue with next_cursor and unchanged query filters when more results are available.
Inputs: end (required), start (required), calendar_id (required), limit, +2 more. Returns: events, next_cursor
update_eventUpdate calendar eventADestructive
Modify an existing event or entire recurring series; individual expanded occurrences are not supported. Target it by resource_id or by calendar_id with uid. Omitted patch fields are preserved, null clears nullable fields, an empty alarms array removes alarms, and expected_etag can prevent a stale write.
Inputs: patch (required), uid, calendar_id, resource_id, +1 more. Returns: end, uid, etag, href, +13 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct action on a distinct resource: create/list/get/update/delete events plus list calendars. The descriptions explicitly clarify boundaries, such as list_events vs get_event and update vs create.
All tool names follow a consistent verb_noun snake_case pattern: create_event, list_events, get_event, update_event, delete_event, list_calendars.
Six tools are well-scoped for a CalDAV server: one discovery tool and a complete event CRUD set. No tool appears redundant or trivial.
The surface covers full event lifecycle plus calendar discovery, which is the core domain. Minor gaps exist around calendar-level operations and individual recurring-occurrence edits, though these are documented limitations rather than dead ends.
Maintenance
Related MCP Connectors
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Model Context Protocol server for todo.vu task management and time tracking.
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
Related MCP Servers
- AlicenseCqualityDmaintenanceA Model Context Protocol server for AI models to access and manipulate Apple Calendar data on macOS through a standardized interface.714MIT
- AlicenseDqualityDmaintenanceA Model Context Protocol server that allows users to interact with their CalDAV, CardDAV, and WebDAV services (calendars, contacts, and files) from Fastmail and Apple iCloud accounts.63MIT
- AlicenseNot gradedqualityCmaintenanceAn HTTP Model Context Protocol (MCP) server exposing iCloud Calendar (CalDAV) tools so MCP-aware clients can list calendars, read events, and create/update/delete events using an iCloud app-specific password.3MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Calendar via native EventKit API with proper recurring event support.13 npm10MIT