icloud-calendar-mcp

Zuverlässiger, leichter Apple iCloud Calendar MCP Server. Nativ in TypeScript/Node.js, verbindet sich über CalDAV direkt mit iCloud; benötigt kein Java, Python, Go, AppleScript, macOS oder Calendar.app.

English summary: A production-oriented, cross-platform TypeScript MCP server for Apple iCloud Calendar. It provides guarded CalDAV CRUD, persistent opaque handles, idempotent writes, ETag concurrency control, recurrence expansion, stdio and secured Streamable HTTP transports.

Installation

Erfordert Node.js 20 oder höher. Es muss ein Apple „App-spezifisches Passwort“ verwendet werden, nicht das Hauptpasswort des Apple-Kontos.

npx icloud-calendar-mcp

App-spezifisches Passwort erstellen: Melden Sie sich bei account.apple.com an, gehen Sie zu „Anmeldung und Sicherheit“ → „App-spezifische Passwörter“. Apple kann die Anzahl gleichzeitig aktiver app-spezifischer Passwörter begrenzen; nach dem Widerruf eines Passworts erhält dieser Dienst AUTH_FAILED.

stdio-Client-Konfiguration:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["-y", "icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "you@example.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

stdout wird nur für JSON-RPC verwendet; alle Logs werden nach stderr geschrieben.

Related MCP server: Chronos MCP

Werkzeuge und MCP-Inhalte

Werkzeuge geben gleichzeitig structuredContent und Text-JSON zurück und deklarieren read-only/destructive/idempotent/open-world-Annotationen. Ressourcen: calendar://calendars. Explizite Benutzervorlagen-Prompts: schedule_event, reschedule_event, find_conflicts; sie treffen keine eigenständigen Terminentscheidungen für den Benutzer.

Ereignisse unterstützen terminiert/ganztägig, Titel, Beschreibung, Ort, URL, RRULE, DISPLAY-Alarm und Teilnehmer. Teilnehmerfelder unterliegen den Einschränkungen von iCloud und Kalenderfreigabeberechtigungen; dieser Dienst meldet das Schreiben von „ATTENDEE“ nicht fälschlicherweise als erfolgreich gesendete Einladung.

Zeit- und Wiederholungsereignis-Semantik

• Terminierte Ereigniseingabe muss ISO 8601-Zeit und IANA-timezone bereitstellen; die Ausgabe gibt die Zeitzone ebenfalls explizit zurück.

• Ganztägige Ereignisse verwenden YYYY-MM-DD für start/end, end ist nicht im Ereignis enthalten. Beispiel: Ein ganztägiges Ereignis am 18. August ist start=2026-08-18, end=2026-08-19.

• iCalendar wird mit ical.js erstellt und geparst, ohne String-Verkettung von Benutzerfeldern; Tests decken DST, UTC und ganztägige Grenzen ab.

• list_events fordert die Erweiterung von RRULE-Vorkommen über CalDAV calendar-data/expand an.

• whole_series unterstützt Aktualisieren/Löschen. single_occurrence, this_and_future geben UNSUPPORTED_OPERATION zurück, wenn die iCloud-Recurrence-Exception-Fähigkeit nicht verifiziert ist, und ändern niemals stillschweigend die gesamte Serie.

HTTP-Modus

HTTP ist standardmäßig deaktiviert. Wenn aktiviert, lauscht es nur auf Loopback, und das Bearer-Token ist mindestens 24 Zeichen lang:

ICLOUD_MCP_TRANSPORT=http \
ICLOUD_MCP_HTTP_TOKEN='replace-with-a-long-random-token' \
ICLOUD_MCP_HTTP_PORT=3000 \
npx icloud-calendar-mcp

• MCP-Endpunkt: POST /mcp

• Health-Check: GET /healthz (greift nicht auf Apple zu und gibt keinen Kontostatus preis)

• Erzwungenes Bearer-Token; feste Host-Allowlist; Origin standardmäßig alle abgelehnt; 1 MiB Standard-Anfragelimit; lokale Lese-/Schreib-Drosselung; Timeout- und Sicherheits-Response-Header-Grenzen.

• Stabile Parameter über ICLOUD_MCP_CONFIG=/absolute/path/config.json setzen, z. B. allowedHosts, allowedOrigins, timeoutMs, maxEvents, Lese-/Schreib-Drosselung und Anfragelimit. Anmeldeinformationen dürfen nicht in diese Datei.

Vollständiger Konfigurationsvertrag in docs/tool-contracts.md, Sicherheitsmodell in docs/security.md.

Zuverlässigkeit

• Die UID von create ist ein stabiler SHA-256-Ableitungswert von request_id; doppelte Anfragen erzeugen kein zweites Ereignis.

• create verwendet If-None-Match: *, update/delete verwenden If-Match mit dem gelesenen ETag.

• Journal wird mit atomarem rename in das Benutzerdatenverzeichnis (standardmäßig ~/.icloud-caldav-mcp/journal.json, mit restriktiven Berechtigungen) geschrieben und speichert Request-Replay und opaque handles.

• 429/5xx/vorübergehende Netzwerkfehler verwenden exponentielles Backoff mit Jitter und respektieren Retry-After; bei fehlendem Response-ETag wird Read-After-Write-Sichtbarkeits-Polling durchgeführt.

• Stabile Fehlercodes: AUTH_FAILED, CALENDAR_NOT_FOUND, EVENT_NOT_FOUND, ETAG_CONFLICT, INVALID_EVENT, RATE_LIMITED, TEMPORARY_UNAVAILABLE, UNSUPPORTED_OPERATION.

Entwicklung und Smoke-Test mit echtem Konto

pnpm install
pnpm check
pnpm pack

Benutzerseitige Änderungen werden mit pnpm changeset protokolliert. Nach dem Push auf main erstellt oder aktualisiert Changesets automatisch eine Release-PR; nach dem Zusammenführen dieser PR wird automatisch über npm Trusted Publishing mit Provenance veröffentlicht. Vor der ersten Aktivierung muss .github/workflows/release.yml in den npm-Paketeinstellungen als Trusted Publisher konfiguriert werden.

CI verwendet Fake-Adapter/HTTP-Fixtures und benötigt kein echtes Apple-Konto. Optionale echte Tests werden nur lokal nach expliziter Bereitstellung von ICLOUD_USERNAME und ICLOUD_APP_PASSWORD ausgeführt: pnpm smoke:icloud. Das aktuelle Smoke-Suite überspringt standardmäßig Schreiboperationen; für die erste echte Verifizierung wird empfohlen, das Discovery/Erstellen/Aktualisieren/Löschen/Recurrence-Exception-Verhalten manuell mit einem dedizierten Testkalender zu überprüfen.

Fehlerbehebung: 401/403 – App-spezifisches Passwort prüfen; 412 – ETag-Konkurrenzkonflikt, bitte list_events/get_event erneut ausführen; 429 – nach Wartezeit erneut versuchen; unbekannter Handle – Journal gelöscht oder Datenverzeichnis geändert. Bitte keine vollständigen CalDAV-URLs, Authorization- oder Ereignistexte in Issues einfügen.

Lizenz

MIT. Implementierung als eigenständiger, originärer Code; das öffentliche Projekt dient nur der Schnittstellen- und Architektur-Differenzanalyse, es wurde kein Quellcode Dritter kopiert.