Skip to main content
Glama

CalDAV MCP Server

TypeScript CI Container License

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

Installation

Voraussetzungen

  • Ein iCloud-Konto mit aktiviertem Kalender.

  • Zwei-Faktor-Authentifizierung für das Apple-Konto aktiviert.

  • Ein App-spezifisches Passwort.

  • 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:latest

Laden Sie das Compose-Beispiel herunter:

curl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yaml

Geben 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 -d

Um einen anderen Host-Port zu veröffentlichen, setzen Sie:

export CALDAV_MCP_PUBLISHED_PORT=18100
docker compose -f compose.example.yaml up -d

Das 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/mcp

Der 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:latest

Container 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 stdio

Im stdio-Modus ist stdout ausschließlich für MCP-Nachrichten reserviert. Um Streamable HTTP lokal auszuführen:

CALDAV_MCP_TRANSPORT=streamable-http pnpm start

Konfiguration

Alle Einstellungen verwenden das Präfix CALDAV_ oder CALDAV_MCP_.

Variable

Erforderlich

Standard

Beschreibung

CALDAV_PROVIDER

Nein

icloud

Anbieterrichtlinie. iCloud ist das unterstützte Profil.

CALDAV_URL

Nein

https://caldav.icloud.com

CalDAV-Erkennungs-URL.

CALDAV_USERNAME

Ja

Keine

Apple-Konto-E-Mail.

CALDAV_PASSWORD

Ja

Keine

App-spezifisches Passwort, nicht das Kontopasswort.

CALDAV_MCP_TRANSPORT

Nein

stdio

stdio oder streamable-http.

CALDAV_MCP_HOST

Nein

0.0.0.0

HTTP-Bind-Adresse.

CALDAV_MCP_PORT

Nein

8100

HTTP-Listening-Port.

CALDAV_MCP_LOG_LEVEL

Nein

INFO

Anwendungsprotokollstufe.

CALDAV_MCP_REQUEST_TIMEOUT_MS

Nein

30000

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/mcp

Wenn der Client das Compose-Netzwerk teilt, verwenden Sie den Dienstnamen und den internen Port:

mcp_servers:
  caldav:
    url: http://caldav-mcp:8100/mcp

Fü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-xxxx

Pinnen 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-mcp

Starten 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.json

In 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-mcp

Der 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 build

Verbinden 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 tools
create_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 eventA
DestructiveIdempotent

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 eventA
Read-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 calendarsA
Read-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 eventsA
Read-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 eventA
Destructive

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

    A4.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: create_event, list_events, get_event, update_event, delete_event, list_calendars.

    Tool Count5/5

    Six tools are well-scoped for a CalDAV server: one discovery tool and a complete event CRUD set. No tool appears redundant or trivial.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers