Cupertino

Bringen Sie Ihren Agenten in Ihren alltäglichen Apple-Apps zum Einsatz.

MCP-Server für die Apple-Apps, die bereits auf Ihrem Mac sind, und die signierte App, die ihnen ihre Berechtigungen einmal statt für jede einzeln gewährt – für jeden Agenten, der MCP spricht, nicht für einen Host.

Inoffiziell. Nicht mit Apple verbunden. Diese steuern die Apps, die bereits auf Ihrem Mac sind.

In Verwendung

Schauen Sie, wie ich in meinem Arbeitspostfach schreibe, und entwerfen Sie diese Antwort im gleichen Ton.

Stellen Sie alles über den Atlas-Start aus meiner Mail, meinen Notizen und meinem Kalender zusammen. Was schulde ich noch?

Verwandle die Aktionspunkte aus dem gestrigen Kunden-Thread in Erinnerungen, fällig am Freitag.

Jede dieser Aussagen trägt eine Einschränkung – ein Konto, eine Datumsgrenze, einen Filter. Das ist der Teil, den der naive osascript-Pfad in 74 Sekunden beantwortet oder falsch beantwortet, und der Grund, warum ein Server seinen Platz verdient: er hält, was das Modell sonst jede Sitzung neu ableiten würde. Die Messungen sind in docs/verify.md; was die Alternativen kosten, steht in docs/alternatives.md.

Die letzte benötigt das Schreib-Gate für Erinnerungen geöffnet. Schreibvorgänge sind pro Oberfläche deaktiviert, bis Sie sie einschalten, und der Schalter entscheidet, ob die mutierenden Werkzeuge überhaupt registriert sind – ein Agent mit deaktivierten Schreibvorgängen kann nicht sehen, dass sie existieren.

Related MCP server: apple-mcp

Oberflächen

Jede Oberfläche ist ein eigener Server und ein eigenes npm-Paket, sodass ein Host nur die Werkzeuge lädt, die er möchte. Sie teilen sich ein Bundle und eine Vollzugriff-auf-Festplatte-Genehmigung, was der ganze Grund ist, warum sie zusammenleben – siehe docs/distribution.md.

Schnellstart

Jeder Server ist auf npm und läuft direkt über npx – für Claude Code eine .mcp.json neben Ihrem Projekt:

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-mail"]
    },
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-notes"]
    }
  }
}

Die Pakete sind MIT und benötigen keinen Lizenzschlüssel. Was sie benötigen, ist eine Berechtigung, und auf npm gewähren Sie sie dem, was sie startet – Ihrem Editor, Ihrem Terminal –, was der Handel ist, den die signierte Cupertino.app vermeiden soll: eine Vollzugriff-auf-Festplatte-Genehmigung, gehalten von einer notarisierten Binärdatei, statt einer pro Host. Siehe docs/licensing.md.

Oder führen Sie sie aus dem Quellcode aus:

git clone https://github.com/mgcrea/mcp-cupertino.git
cd mcp-cupertino
pnpm install
pnpm build

und zeigen Sie dann Ihrem Host auf packages/<surface>/dist/cli.js mit absolutem Pfad.

Schreibvorgänge sind deaktiviert, es sei denn, Sie fragen danach – siehe Konfiguration.

Wenn Sie stattdessen über die Menüleisten-App laufen, wird jeder Server über die Brücke geleitet, sodass der Vollzugriff auf die Festplatte Cupertino gewährt wird und nicht dem Editor, der den Server gestartet hat:

make run      # build Cupertino.app, point it at packages/*/dist, launch it
make smoke    # handshake every server through the bridge

Die eingecheckte .mcp.json des Repos ist für diesen Pfad verdrahtet. make allein listet jedes Ziel auf.

Beachten Sie die unterschiedlichen Servernamen. Von Hand wie oben verdrahtet, ist ein Server apple-mail und läuft unter der Genehmigung seines Host-Prozesses. Von Cupertino verdrahtet ist er cupertino-mail, weil dieser Eintrag auf die Brücke der App zeigt und unter der Genehmigung der App läuft. Zwei Namen für zwei Bereitstellungen, und Sie können beide haben. Die App berührt nur ihre eigenen cupertino-*-Schlüssel – ein apple-mail-Eintrag, der zu einem anderen Server gehört, bleibt unberührt.

Cupertino ist Maschinenkonfiguration, keine Projektabhängigkeit, also gehört es in eine benutzerspezifische Konfiguration: eine Datei für Claude Desktop, Cursor, LM Studio und Windsurf, und --scope user für die CLIs, was die kopierbaren Befehle der App verwenden. Bewusst nicht --scope project, das eine .mcp.json schreibt, die zum Committen gedacht ist – dieser Eintrag ist ein absoluter Pfad in ein Bundle auf einem Mac, unterstützt durch die Vollzugriff-auf-Festplatte-Genehmigung einer Person, und er wäre für einen Teamkollegen nutzlos und unweise, ihn anzubieten.

Welche Clients geschrieben werden und welche einen Befehl erhalten, ist keine Frage der Beliebtheit. Die App führt eine Zusammenführung in eine Konfiguration nur durch, wenn sie striktes JSON mit Servern unter mcpServers ist; Visual Studio Code ist JSONC und Codex ist TOML, und das erneute Serialisieren würde die Kommentare in einer von Hand gepflegten Datei löschen. Claude Codes ~/.claude.json ist striktes JSON, aber es enthält Anmeldeinformationen und laufende Sitzungen schreiben gleichzeitig hinein, sodass ein Lesen-Ändern-Schreiben von einer Menüleiste die Änderung eines anderen verlieren könnte. Diese drei erhalten eine Zeile zum Einfügen. ChatGPT fehlt vollständig: Es akzeptiert entfernte HTTP-Connector und kann keinen lokalen stdio-Server starten.

Die eigene .mcp.json dieses Repos ist die Ausnahme, und sie benennt ihre Server cupertino-*-dev absichtlich: Sie zeigt auf apps/apple/.build, sodass die Arbeit an der App bedeutet, die Entwicklungsversion und die installierte nebeneinander zu haben. Claude Code meldet Server mit demselben Namen in zwei Bereichen als Konflikt, anstatt einen auszuwählen, also ist das Suffix das, was beide nutzbar hält.

Cupertino.app benötigt macOS 26 oder neuer – sein Symbol ist ein Icon-Composer-Bundle, das nichts Älteres rendern kann. Die Server selbst sind einfaches Node und haben keine solche Untergrenze; nur die Menüleisten-App hat sie.

Berechtigungen

Zwei separate macOS-Genehmigungen, und sie landen auf dem Prozess, der den Server gestartet hat – Ihrem Editor, Ihrem Terminal oder Cupertino – niemals auf Mail, Notizen oder Erinnerungen selbst.

Systemeinstellungen → Datenschutz & Sicherheit → Vollzugriff auf die Festplatte → die startende App hinzufügen, dann neu starten. Das Gewähren an Mail.app bewirkt nichts; der Leser benötigt die Berechtigung, nicht Mail.

Was ohne Vollzugriff auf die Festplatte funktioniert:

Werkzeuge, die den Index benötigen, verschwinden nicht, wenn er fehlt – die Werkzeugliste ist eine reine Funktion von allowWrites und nichts anderem, weil MCP-Clients sie zwischenspeichern. Sie geben ein strukturiertes degraded Ergebnis zurück, das benennt, was fehlt. apple_mail_diagnostics / apple_notes_diagnostics melden, welche Spur aktiv ist und wie das Fehlende gewährt werden kann.

Werkzeuge

Lesewerkzeuge sind immer registriert. Schreibwerkzeuge sind unsichtbar, es sei denn, Schreibvorgänge sind aktiviert – nicht nur verweigert.

Mail

Notizen

Erinnerungen

Calendar

list_events expandiert wiederkehrende Ereignisse, sodass ein wöchentliches Stand-up einmal pro Woche zurückgegeben wird. Jedes Ergebnis trägt das Fenster, das die Expansion bekanntermaßen abdeckt, und setzt truncated, wenn ein Bereich darüber hinausläuft, anstatt zu kurz zurückzukommen – eine kurze Ereignisliste ist von einem freien Nachmittag nicht zu unterscheiden.

Contacts

resolve_handles wandelt Telefonnummern und E-Mail-Adressen in Namen um, was die Messages-Oberfläche überhaupt erst lesbar macht. Lies den status jedes Ergebnisses, anstatt anzunehmen, dass ein Name zurückkam: unknown ist häufig und kein Fehler, und ambiguous bedeutet, dass zwei Kontakte die Nummer teilen, sodass kein Name zurückgegeben wird, statt zu raten.

Es gibt kein Lösch-Tool. Das Scripting-Wörterbuch von Contacts hat keinerlei Löschbefehl, und Schreibvorgänge laufen hier auf jeder Oberfläche über Apple Events, da der Speicher grundsätzlich schreibgeschützt ist. Siehe docs/contacts.md.

Messages

Ein Schreib-Tool, weil das Wörterbuch genau einen brauchbaren Befehl hat. sdef listet send, login und logout; die anderen beiden würden den Benutzer auf jedem eigenen Gerät von iMessage abmelden. Es gibt kein Verb für Bearbeiten, Löschen, Als-gelesen-Markieren oder Reagieren, das offengelegt werden könnte.

Dies ist die einzige Oberfläche, auf der Apple Events eine reine Schreibspur und sonst nichts ist – jeder Lesevorgang darüber schlägt fehl. Wenn APPLE_MESSAGES_ALLOW_WRITES deaktiviert ist, wird also nie ein Apple Event gesendet und nie eine Automatisierungsberechtigung angefragt.

send_message bevorzugt eine chatRef aus list_chats gegenüber einem rohen Handle, weil Messages sich weigert, Teilnehmer für ein Skript aufzulisten: Eine bestehende Konversation ist das einzige Ziel, das zuverlässig adressiert werden kann. Apple Events liefert keine Kennung für das Gesendete zurück, daher wird das Ergebnis mit chat.db abgeglichen – reconciliation: "matched" trägt eine echte Message-Referenz, und "pending" bedeutet, dass Messages den Sendevorgang akzeptiert, die Zeile aber noch nicht geschrieben hat. Pending ist kein Fehler, und ein erneuter Versuch sendet die Nachricht doppelt.

Bei etwa 3 % der Nachrichten in der gesamten Historie bleibt der Text nur in einem archivierten NSArchiver-Blob erhalten, den SQL nicht erreichen kann – und Apple hat Anfang 2026 aufgehört, die Klartextspalte zu schreiben, daher sind es für alles Neuere ~100 %. Dieser Server dekodiert sie; textSource gibt bei jedem Ergebnis an, welche Spur geantwortet hat. Siehe docs/messages.md.

Safari

Schreibgeschützt, und die Schreibspalte ist absichtlich leer. Das Öffnen einer URL oder das Hinzufügen zur Leseliste ist ein Apple Event, das einen echten, sichtbaren Browser navigiert, und auf dieser Oberfläche wurde noch nie ein Schreibvorgang erprobt.

list_tabs ist das einzige Tool im gesamten Bundle, das ohne Vollen Festplattenzugriff funktioniert – es benötigt stattdessen eine Automatisierungsberechtigung, und Safari muss laufen. Wenn das history-Feld eines Tabs null ist, bedeutet das nicht im Verlauf gefunden, niemals „nie besucht“: Nur etwa 55 % der geöffneten Tabs entsprechen einer Verlaufszeile, weil Weiterleitungen, Sitzungsparameter und nie im Verlauf gespeicherte Seiten alle eine URL erzeugen, die schlicht nicht vorhanden ist.

Es gibt kein do JavaScript-Tool. Dieses Verb benötigt „JavaScript von Apple Events erlauben“, einen Umschalter im Safari-Entwicklermenü, der keine TCC-Berechtigung ist und dessen eigener Zustand nicht zuverlässig ausgelesen werden kann. Es auszuliefern würde bedeuten, eine gesunde Oberfläche zu melden, deren mächtigste Fähigkeit stillschweigend scheitert. Siehe docs/safari.md.

Alle Namen tragen das Präfix apple_mail_ / apple_notes_ / apple_reminders_ / apple_calendar_ / apple_contacts_ / apple_messages_ / apple_safari_.

Konfiguration

Nur Umgebungsvariablen – diese Server besitzen selbst kein Geheimnis, daher gibt es keine Konfigurationsdatei. Das Präfix ist APPLE_MAIL_, APPLE_NOTES_, APPLE_REMINDERS_, APPLE_CALENDAR_, APPLE_CONTACTS_, APPLE_MESSAGES_ oder APPLE_SAFARI_.

allowWrites steuert Mutationen, aber bei Mail ist der größere Schadensradius das Lesen eines gesamten Archivs – genau dafür ist *_ACCOUNTS da, und es wird an genau einer Stelle durchgesetzt, sodass kein Abfragepfad daran vorbeikommt. Mail akzeptiert außerdem *_ROOT, *_ENVELOPE_INDEX, *_DEGRADED_MAX_MESSAGES, *_BODY_MAX_BYTES, *_BODY_SCAN_MAX, *_BODY_SCAN_BYTES und *_MAILBOX_CACHE_TTL_MS; siehe packages/mail/src/config.ts.

Die App

Die Menüleiste ist die gesamte Oberfläche von Cupertino – es gibt kein Dock-Symbol und kein Hauptfenster.

Das Fenster Aktivität zeichnet nur Tool-Namen auf – niemals Argumente, Nachrichteninhalte oder Ergebnisse. Es ist die Antwort auf „Was hat der Assistent gerade mit meiner Mail gemacht?“ und der Grund, warum die Server unter einer sichtbaren App laufen und nicht in dem Editor, der sie gestartet hat.

Schreibvorgänge sind pro Oberfläche deaktiviert, bis du sie einschaltest, und der Schalter entscheidet, ob die mutierenden Tools überhaupt registriert werden – ein Assistent mit deaktivierten Schreibvorgängen kann nicht sehen, dass es sie gibt.

Warum eine einzige App

Voller Festplattenzugriff ist eine unteilbare, die gesamte Festplatte betreffende Berechtigung. Sie pro Oberfläche zu gewähren bringt keine Eingrenzung und kostet jedes Mal einen Gang zu den Systemeinstellungen. Deshalb wird jede Oberfläche in einer einzigen signierten und notarisierten App namens Cupertino ausgeliefert. docs/distribution.md hält außerdem fest, warum der Mac App Store nichts davon hosten kann, damit diese Frage nicht wieder aufgemacht wird.

Aber die Berechtigung ist nicht das Einzige, was die App besitzt, und sie ist nicht der einzige Grund, die Server unter ihr laufen zu lassen statt unter einem Editor:

docs/alternatives.md ist die ehrliche Version dieser Liste: was sonst Apple Mail für einen Assistenten liest und wo diese Tools voraus sind.

Dokumentation

In Arbeit

pnpm build          # every package
pnpm test           # every package
pnpm typecheck
pnpm lint
pnpm format

Die Marketing-Website ist ein eigener Arbeitsbereich und wird von Hand bereitgestellt:

pnpm --filter @mgcrea/cupertino-website dev     # astro dev
pnpm --filter @mgcrea/cupertino-website build   # static build

Es wird aus der Design-Canvas in .idea/design/ erstellt und liest seine Tool-Zahlen aus packages/*/src/tools/ und nicht aus dieser Datei – siehe apps/website.

Die Swift-Hälfte ist xcodebuild, benannt durch das Makefile und nicht davon umschlossen:

make app            # build Cupertino.app (Debug)
make run            # build, point at packages/*/dist, launch
make smoke          # handshake every server through the bridge
make stop           # quit and remove the socket

Die Screenshots der App werden aufgenommen und nicht von Hand erstellt – apps/apple/Screenshots/ enthält die Konfiguration und die festgeschriebenen Goldens, und die Website rendert die Ausgabe:

make screenshots          # capture, gate against the goldens, compose both sets
make screenshots-check     # gate only — fails if the UI drifted
make screenshots-update    # accept the captures as the new goldens (review the diffs first)
make screenshots-selftest  # prove the gate fails when it should

Ein Lauf übernimmt den Zeiger und die aktive App im Moment jeder Aufnahme, also benutze den Rechner nicht, während er läuft. Es benötigt die Bildschirmaufnahme-Berechtigung für das Terminal, niemals für Cupertino selbst. make screenshots-doctor prüft das und die zwei anderen Dinge, die sonst stillschweigend fehlschlagen: ob die Beschriftungsschrift aufgelöst wird und ob die Ausgabegröße eine ist, die ein Store akzeptieren würde.

Was die Screenshots zeigen, sind Fixture-Daten aus apps/apple/Cupertino/DemoSeed.swift, nicht dieser Mac: Im -ScreenshotMode startet die App keinen Host, seedet ihr eigenes Log und ihre Sitzungen und beantwortet die Berechtigungs- und Store-Fragen aus einer Tabelle. Ohne das würden die Bilder den TCC-Zustand eines Laptops melden und sein Home-Verzeichnis in die Marketing-Website drucken.

Phase-0-Sonden sind repo-weit und schreibgeschützt. Sie benötigen die Berechtigung der Oberfläche, die sie messen, und schwärzen ihre Ausgabe auf Zählungen, Zeitmessungen und DDL:

pnpm probe:mail      # Envelope Index — needs Full Disk Access
pnpm probe:mail-body # which lane can search message bodies — needs Full Disk Access
pnpm probe:notes     # Notes — the Apple Events half runs without it
pnpm probe:reminders # Reminders — the store path is a glob, so finding it is itself privileged
pnpm probe:messages  # chat.db — no Apple Events read lane exists, so this one needs the grant
                     #   --send-target=<handle> also checks the send lane's targeting, without sending
pnpm probe:calendar  # settles whether Calendar has a file lane at all
pnpm probe:safari    # History.db, and the Reading List hiding inside Bookmarks.plist
pnpm probe:contacts  # the resolver Messages needs — its own TCC grant, not Full Disk Access

Jede untersuchte Oberfläche hat jetzt ein Paket. Safari ist schreibgeschützt – es registriert kein mutierendes Tool, und das ist eine dokumentierte Entscheidung und keine Auslassung: Das Öffnen einer URL oder das Hinzufügen zur Leseliste navigiert einen echten, sichtbaren Browser und wurde nie untersucht. Siehe docs/safari.md. Messages registriert genau ein Schreib-Tool, send_message, das das gesamte ist, was sein Skript-Wörterbuch tun kann. Jede Sonde degradiert statt zu beenden – eine App, die nicht läuft, oder eine Berechtigung, die nicht erteilt wurde, wird als Befund gemeldet – und keine von ihnen startet eine App, es sei denn, du übergibst --launch. Ihr gemeinsamer Mechanismus lebt in scripts/lib/probe-kit.mjs.

Releases werden pro Paket getaggt, also benennt ein Tag, was es veröffentlicht: mail-v1.1.0, reminders-v1.1.0, calendar-v1.1.0, core-v1.1.0. Die App ist mit app-v1.1.0 getaggt und veröffentlicht auf ihrer eigenen Spur – ein signiertes, notarisiertes Cupertino.zip, das an das GitHub-Release angehängt ist, plus seine SHA-256. Siehe docs/distribution.md.

Das Repo ist mcp-cupertino; die npm-Pakete bleiben @mgcrea/mcp-apple-*, weil das ist, wonach die Leute auf npm suchen. Keiner der Namen ist tragend. Die Bundle-Kennung io.mgcrea.cupertino ist die Zeichenfolge, die tatsächlich zählt, denn ihre Änderung würde die Full Disk Access-Gewährung jedes Benutzers ungültig machen.

Lizenz

Zwei, weil die Hälften nicht dasselbe sind.

Cupertino verlangt Full Disk Access, also bleibt der Quellcode lesbar – das ist es, was einer solchen Gewährung geschuldet ist, und das Lesen ist der Punkt. Das Ausführen ist eine separate Frage: Die Lizenzprüfung lebt im Quellcode, also fragt jeder Build nach einem Schlüssel, deinem oder unserem. Was verkauft wird, ist das notarisierte Binär und die Wartung dahinter. Die Server sind MIT und laufen von selbst ohne jeden Schlüssel. Die Begründung steht in docs/licensing.md.