mcp-ical-swift

Ein lokaler MCP-Server für Apple Kalender, der ein kompiliertes Swift-Binary verwendet, um die TCC-Beschränkungen von macOS Sequoia zu umgehen.

Warum existiert dieses Projekt?

Unter macOS Sequoia (26.x) können Headless-Prozesse keinen Kalenderzugriff über den Standard-TCC-Mechanismus (Transparency, Consent, and Control) erhalten:

• EventKit von Python (z. B. PyObjC) erfordert kTCCServiceCalendar, was nur über einen Systemdialog gewährt werden kann, den Headless-Prozesse nicht auslösen können. Es gibt unter Sequoia keinen +-Button in den Systemeinstellungen > Datenschutz & Sicherheit > Kalender.

• AppleScript via osascript erfordert kTCCServiceAppleEvents (Automatisierungsberechtigung), die dem aufrufenden Binary (normalerweise node oder bun) zugeschrieben wird. Direkte Änderungen an der TCC-Datenbank werden von den Integritätsprüfungen des TCC-Daemons stillschweigend ignoriert.

• icalBuddy und andere Homebrew-Tools verwenden intern EventKit und stoßen auf dieselbe Hürde.

Das kompilierte Swift-Binary (swiftc) funktioniert, weil es ein von Apple signiertes Mach-O-Executable erzeugt, das den Kalender-TCC von der Swift-System-Toolchain erbt. Wenn Node/Bun dieses Binary über execFileSync startet, meldet EventKit authorizationStatus = .fullAccess und gibt Kalenderdaten zurück.

Funktionen

• Alle Kalender auflisten

• Termine innerhalb eines Datumsbereichs auflisten

• Termine nach Stichwort suchen

• Neue Termine erstellen (mit Kalender, Ort, Notizen, Unterstützung für ganztägige Termine)

• Bestehende Termine aktualisieren

• Vollständige Termindetails per UID abrufen

• Termine löschen

• Läuft vollständig lokal über stdio -- kein Netzwerk, keine API-Schlüssel, keine Cloud

Voraussetzungen

• macOS Sequoia (26.x) oder neuer

• Bun 1.1+

• Xcode Command Line Tools (xcode-select --install) für swiftc

• Kalenderdaten in Apple Kalender (iCloud, Exchange oder lokale Kalender)

Installation

git clone https://github.com/Sealjay/mcp-ical-swift.git
cd mcp-ical-swift
bun install
bun run build

Das build-Skript kompiliert src/calendar-reader.swift zu bin/calendar-reader.

MCP-Client-Konfiguration

Claude Code

claude mcp add --transport stdio ical --scope user -- bun run /absolute/path/to/mcp-ical-swift/src/index.ts

OpenClaw

{
  "mcp": {
    "servers": {
      "ical": {
        "command": "bun",
        "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
      }
    }
  }
}

Claude Desktop

Fügen Sie dies zur claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "ical": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
    }
  }
}

Tools

Funktionsweise

MCP Client (Claude, OpenClaw, etc.)
  --> stdio --> Bun MCP server (src/index.ts)
    --> execFileSync --> compiled Swift binary (bin/calendar-reader)
      --> EventKit framework --> Apple Calendar data

Das Swift-Binary wird einmal kompiliert (bun run build) und für jeden Tool-Aufruf synchron aufgerufen. Es gibt JSON an stdout aus, das der Bun-MCP-Server in MCP-Tool-Ergebnisse verpackt. Der Server verwendet execFileSync (keine Shell-Ausführung), um Injektionsrisiken zu vermeiden.

Die entscheidende Erkenntnis: swiftc-kompilierte Binaries sind von Apple signiert und erben den Kalender-TCC von der System-Toolchain. Dies umgeht die TCC-Beschränkungen, die Node, Bun, Python und AppleScript daran hindern, in Headless-Kontexten auf Kalender zuzugreifen.

Datenschutz und Sicherheit

• Dieser Server greift standardmäßig auf alle Kalender auf dem System zu (iCloud, Exchange, lokal, geteilt, abonniert). Sie können pro Anfrage nach Kalendernamen filtern, indem Sie den optionalen calendar-Parameter bei list_events und search_events verwenden.

• Terminnotizen werden in den Antworten zurückgegeben und können sensible Daten enthalten (Meeting-PINs, Passwörter, persönliche Details). Berücksichtigen Sie dies, wenn Sie einem MCP-Client Zugriff gewähren.

• Schreibvorgänge (create_event, update_event, delete_event) sind ohne Bestätigungsschritt verfügbar. Ein MCP-Client (oder eine Prompt-Injektion innerhalb eines solchen) könnte Ihre Kalenderdaten ändern.

• Die gesamte Kommunikation erfolgt lokal über stdio -- es werden keine Daten an externe Dienste gesendet.

• Um eine Sicherheitslücke zu melden, siehe SECURITY.md.

Einschränkungen

• Nur macOS (erfordert EventKit und die Swift-Toolchain)

• Erfordert Bun-Laufzeitumgebung

• Das Swift-Binary wird einmal kompiliert und pro Tool-Aufruf synchron aufgerufen -- nicht für sehr hohen Durchsatz geeignet

• Änderungen an wiederkehrenden Terminen gelten nur für die einzelne Instanz (.thisEvent-Spanne)

• Der Kalenderzugriff hängt davon ab, ob macOS TCC dem kompilierten Binary die Berechtigung erteilt

Fehlerbehebung

"Calendar access is not granted"

Das kompilierte Binary muss mindestens einmal aus einem Kontext heraus ausgeführt werden, der über Kalender-TCC verfügt. Führen Sie den Build und Test aus:

bun run build
bin/calendar-reader list-events $(date +%Y-%m-%d)

Wenn dies Termine zurückgibt, hat das Binary Kalenderzugriff. Falls nicht, versuchen Sie es über Terminal.app (das normalerweise über Kalender-TCC-Berechtigungen verfügt).

Termine sind leer

Überprüfen Sie, ob Sie Kalender in Apple Kalender konfiguriert haben. Führen Sie aus:

bin/calendar-reader list-calendars

Kompilierung schlägt fehl

Stellen Sie sicher, dass die Xcode Command Line Tools installiert sind:

xcode-select --install

Lizenz

MIT