Apple Calendar MCP

Apple Calendar MCP ist ein lokaler Model-Context-Protocol-Server, der KI-Assistenten sicher mit Apple Calendar unter macOS verbindet.

Er verwendet einen TypeScript-MCP-Server, einen Swift-EventKit-Helper, lokalen SQLite-Status und eine native macOS-Setup-App. Die Kalenderdaten bleiben auf dem Mac, die Benutzer wählen aus, welche Kalender sichtbar sind, und Schreibvorgänge werden durch Berechtigungsmodi, Bestätigungsstufen, Duplikatprüfungen, Idempotenz, Rollback-Aufzeichnungen, Audit-Logs und Änderungsfeeds geschützt.

Hauptfunktionen

• Kalender, Ereignisse, Verfügbarkeit und Berechtigungen von Apple Calendar über MCP-Tools lesen.

• Ereignisse mit standardmäßiger Vorschau-Bestätigung erstellen, aktualisieren, verschieben und löschen.

• Kalender-Allowlists serverseitig durchsetzen, sodass gesperrte Kalender für Agenten unsichtbar bleiben.

• Rollback-Aufzeichnungen, Audit-Aufzeichnungen, kompakte Snapshots und token-effiziente Änderungsfeeds verfolgen.

• Client-Konfigurationen für Claude Desktop, Codex, Cursor, OpenClaw und generische MCP-Clients generieren.

• Einen nativen macOS-Setup-Assistenten für Kalenderberechtigungen, Allowlists, Berechtigungsmodus, Konfigurationserstellung und -überprüfung bereitstellen.

Related MCP server: nucleus-apple-mcp

Architektur

flowchart TD
  A["MCP Client<br/>Claude, Codex, Cursor, OpenClaw"] --> B["TypeScript MCP Server"]
  B --> C["Calendar Service Layer"]
  C --> D["Swift EventKit Helper"]
  D --> E["Apple Calendar / EventKit"]
  C --> F["SQLite Local State"]
  F --> G["Config, Audit, Rollback,<br/>Snapshots, Change Feed,<br/>Idempotency"]
  H["Native macOS Setup App"] --> D
  H --> F

Der MCP-Server kommuniziert über stdio. Logs werden nach stderr oder in eine optionale lokale Logdatei geschrieben, niemals nach stdout, sodass der MCP-Protokollverkehr sauber bleibt.

Voraussetzungen

• macOS mit Apple-Calendar- und EventKit-Zugriff.

• Node.js >=22.5.

• Swift-Toolchain über Xcode Command Line Tools oder Xcode.

• Einen MCP-Client wie Claude Desktop, Codex, Cursor, OpenClaw oder einen anderen stdio-kompatiblen Client.

Aus dem Quellcode installieren

git clone <repo-url>
cd apple-calendar-mcp
npm install
npm run build
npm run helper:bundle
npm run helper:setup

Die Setup-App führt durch:

1. Erläuterung und Anforderung der Kalenderberechtigung.

2. Auswahl der Kalender-Allowlist.

3. Auswahl des Berechtigungsmodus.

4. Generierung der MCP-Client-Konfiguration.

5. Überprüfungen und Testverbindung.

Die generierte lokale Konfiguration wird gespeichert unter:

~/Library/Application Support/AppleCalendarMCP/

MCP-Client-Einrichtung

Generierte validierte Client-Konfigurationen:

npm run client-configs:generate

Kopieren Sie die generierte Datei aus .generated/client-configs/ in Ihren Client oder führen Sie einen Merge durch:

• Claude Desktop: claude_desktop_config.json

• Codex: codex.config.toml an ~/.codex/config.toml anhängen

• Cursor: cursor.mcp.json nach ~/.cursor/mcp.json oder in ein Projekt-.cursor/mcp.json kopieren oder zusammenführen

• OpenClaw: openclaw.openclaw.json in ~/.openclaw/openclaw.json einfügen

• Generische MCP-Clients: generic-mcp-client.json verwenden

Nach dem Kopieren validieren:

npm run client-configs:validate
npm run client-configs:diagnose

Die generierten Konfigurationen verwenden eine absolute Node-Ausführungsdatei, einen absoluten MCP-Servereinstiegspunkt und einen Umgebungsblock. Befehl und Argumente werden niemals zu einer Shell-Zeichenkette zusammengeführt, was Fehler bei Pfaden mit Leerzeichen vermeidet.

npx-Startpfad

Das veröffentlichbare Serverpaket stellt diese Binärdatei bereit:

npx apple-calendar-mcp

Für die lokale Entwicklung und Release-Kandidaten bevorzugen Sie:

npm run start:mcp

Veröffentlichen Sie vor der Veröffentlichung auf npm die internen Workspace-Pakete in Abhängigkeitsreihenfolge oder verwenden Sie die Release-Artefakte, die von npm run release:package erzeugt werden.

Sicherheitsmodell

Apple Calendar MCP ist auf Verteidigung in der Tiefe ausgelegt:

• Für den EventKit-Zugriff ist die macOS-Kalenderberechtigung erforderlich.

• Kalender-Allowlists schränken ein, welche Kalender Agenten sehen können.

• Die Modi Schreibgeschützt, Vor dem Schreiben fragen, Vertrautes Schreiben und Voller Schreibzugriff steuern das Schreibrisiko.

• MVP-Schreibvorgänge erfordern eine explizite Bestätigung oder einen Vorschau-Bestätigungsablauf.

• Zerstörerische und mehrdeutige Vorgänge geben semantische Fehler zurück, anstatt zu raten.

• Schreibvorgänge für Serientermine erfordern einen expliziten Geltungsbereich.

• Kalenderinhalte werden als nicht vertrauenswürdige Eingabe behandelt.

• Audit-Aufzeichnungen, Rollback-Aufzeichnungen, Idempotenzschlüssel und Änderungsfeeds werden lokal geschrieben.

Das vollständige Sicherheitsmodell finden Sie unter docs/Security Specification.md.

Screenshots

Platzhalter für Veröffentlichungsscreenshots:

• Willkommens- und Kalenderberechtigungsschritt des Setup-Assistenten.

• Schritt für Kalender-Allowlist und Berechtigungsmodus.

• Schritt für Clientkonfiguration und -überprüfung.

• Bildschirm für Einstellungen und Diagnose.

Nehmen Sie Screenshots von der signierten Veröffentlichung auf, bevor Sie sie öffentlich verteilen.

Fehlerbehebung

• Kalenderzugriff verweigert: Öffnen Sie Systemeinstellungen > Datenschutz & Sicherheit > Kalender und aktivieren Sie die Hilfs-App.

• MCP-Serverstart in der Einrichtung rot: Führen Sie npm run build aus und vergewissern Sie sich, dass packages/mcp-server/dist/index.js vorhanden ist.

• Cursor oder Codex kann keine Verbindung herstellen: Generieren Sie die Konfigurationen mit npm run client-configs:generate neu und stellen Sie sicher, dass die kopierte Konfiguration absolute Pfade verwendet.

• Der Client sieht den Server, aber keine Tools: Starten Sie den MCP-Client nach Konfigurationsänderungen neu und führen Sie dann npm run client-configs:diagnose aus.

• Die Trennung von stdout/stderr schlägt fehl: Entfernen Sie jegliche stdout-Protokollierung aus dem MCP-Serverpfad; Logs müssen nach stderr gehen.

• Große Lesevorgänge schlagen fehl: Verwenden Sie engere Datumsbereiche. Der Lesedienst unterteilt große Fenster intern in Blöcke, aber sehr große EventKit-Anfragen müssen möglicherweise wiederholt werden.

Entwicklung

npm install
npm run build
npm test
npm run helper:bundle
npm run helper:setup

Nützliche Befehle:

• npm run typecheck

• npm run client-configs:generate

• npm run client-configs:validate

• npm run release:verify

• npm run release:package

Lesen Sie docs/Development Guide.md, bevor Sie sicherheitsrelevante Änderungen vornehmen.

Repository-Struktur

apps/macos-helper/        Swift EventKit bridge and native setup app
packages/mcp-server/      MCP stdio server and tool registration
packages/calendar-service/Business logic for reads, writes, rollback, snapshots
packages/sqlite-store/    Local SQLite persistence and migrations
packages/shared/          Shared schemas and typed contracts
scripts/                  Helper, config, diagnostics, and release scripts
tests/                    Phase-based safety and behavior tests
docs/                     Consolidated maintainer and release documentation

Veröffentlichung

Reproduzierbare lokale Release-Artefakte erstellen:

npm run release:package

Artefakte und Prüfsummen werden geschrieben nach:

dist/release/

Der GitHub-Release-Workflow führt dasselbe Paketskript bei Tag-Pushes aus, die mit v* übereinstimmen.

Roadmap

• Signierte und notarisierte macOS-Release-Pakete.

• Öffentlicher npm-Veröffentlichungsworkflow nach Bestätigung des Paketnamensraums.

• Weitere End-to-End-Smoke-Tests für unterstützte MCP-Clients.

• Erweiterte Benchmarks für Snapshot-/Änderungsfeed-Paginierung.

• Bessere In-App-Screenshot-Erfassung und öffentliche Dokumentationsressourcen.

Mitwirken

Sicherheit, Zuverlässigkeit, Benutzervertrauen, MCP-Konformität und Wartbarkeit haben Vorrang vor Bequemlichkeit. Halten Sie Änderungen begrenzt, führen Sie die vollständige Testsuite aus und aktualisieren Sie die Dokumentation, wenn sich das Verhalten ändert. Umgehen Sie keine Berechtigungsprüfungen, Allowlists, Bestätigungsstufen, Rollback-Aufzeichnungen, Audit-Aufzeichnungen, Idempotenzprüfungen oder semantischen Fehler.

Beginnen Sie mit:

• docs/Product Specification.md

• docs/Technical Specification.md

• docs/Security Specification.md

• docs/Development Guide.md

• docs/Installation Guide.md

• docs/Release Checklist.md