macos-mcp

Steuern Sie Reminders, Calendar, Notes, Mail, Messages und Contacts auf macOS über einen KI-Agenten oder über die Shell.

Apple bietet drei Automatisierungsoberflächen für diese Apps, und jede versagt an irgendeiner Stelle. EventKit erreicht Notes, Mail, Messages oder Contacts nicht. JXA-Lesevorgänge von Messages geben unter Sonoma und später nichts zurück. JXA-Lesevorgänge von Mail laufen bei 60 Sekunden in einen Timeout, wenn ein echter Posteingang verwendet wird. Dieses Projekt verwendet die Brücke, die pro App funktioniert, und dokumentiert warum in DECISION.md.

Erfordert einen Mac. Diese Brücken sind EventKit, Apple Events und SQLite-Lesevorgänge lokaler Apple-Datenbanken. Es gibt keine Linux-, Windows-, iOS-, Android- oder Browser-Version.

Drei Verwendungsmöglichkeiten

Als MCP-Server. Lokaler stdio-Transport, funktioniert mit jedem MCP-fähigen Client auf demselben Mac (Claude Code, Claude Desktop, Cursor, Zed, Continue, ChatGPT-Desktop). Acht Tools, aufgelistet unter Tools.

Als Agenten-Fähigkeit. Dieselben Brücken, aufgerufen als Shell-Befehle, ohne Tool-Schemas im Kontext. Ein MCP-Server legt alle acht Tool-Definitionen zu Sitzungsbeginn vor das Modell, unabhängig davon, ob die Sitzung eine Mac-App berührt; eine Fähigkeit ist eine Beschreibungszeile, bis etwas sie auslöst. Siehe skills/macos/ für die Fähigkeit und docs/mcp-vs-skill.md für die Entscheidung.

Als CLI. EventKitCLI ist ein eigenständiges Swift-Binary, das JSON auf stdout ausgibt. Die JXA- und SQLite-Rezepte in der Fähigkeit laufen überall dort, wo eine Shell existiert.

Related MCP server: Apple MCP

Schnellstart

Als Claude-Code-Plugin installieren

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

Führen Sie diese Befehle in Claude Code aus. Das Plugin verdrahtet den MCP-Server über npx -y mcp-macos, sodass kein separater Installationsschritt erforderlich ist.

Von npm installieren

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

Oder über MCPB installieren (Claude Desktop)

Laden Sie das .mcpb-Bundle vom neuesten GitHub-Release herunter und ziehen Sie es auf Claude Desktop. Das Bundle enthält ein vorgefertigtes universelles Swift-Binary (arm64 + x86_64), sodass keine Xcode Command Line Tools erforderlich sind.

Oder aus dem Quellcode erstellen

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

Einrichtung überprüfen

macos-mcp --check   # or: node dist/index.js --check

Prüft macOS-Version, Node.js, EventKit-Binary, Vollzugriff auf die Festplatte und JXA-Automatisierungsberechtigungen.

Oder als Fähigkeit statt als Server verwenden

Kopieren Sie die Fähigkeit in das Fähigkeiten-Verzeichnis Ihres Agenten. Kein MCP-Server, keine Tool-Schemas im Kontext.

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

Die Fähigkeit ruft EventKitCLI, osascript und sqlite3 direkt auf, daher benötigt sie das Swift-Binary im PATH:

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

Die gleichen Berechtigungen gelten in beiden Fällen. Siehe Berechtigungen.

Tools

Sowohl die Unterstrich-Notation (reminders_tasks) als auch die Punkt-Notation (reminders.tasks) funktionieren.

Design-Hinweise

• SQLite für Lesevorgänge, JXA für Schreibvorgänge. JXA-Lesevorgänge von Mail skalieren nicht und erreichen bei echten Posteingängen 60-Sekunden-Timeouts; JXA-Lesevorgänge von Messages sind unter macOS Sonoma und später vollständig defekt. Dieses Projekt liest chat.db und den Envelope Index von Mail direkt, einschließlich der Gmail-labels-Join-Tabelle für [Gmail]/All Mail-Konten. Schreibvorgänge laufen weiterhin über JXA, da Apple Events die einzige API ist, die sie auslöst. Siehe ADR-001.

• Pro-App-Hybrid-Backend. Jede App verwendet die Brücke, die funktioniert: ein Swift-CLI über EventKit für Reminders und Calendar, JXA für Notes, Contacts, Mail-Schreibvorgänge und Messages-Senden, SQLite für Mail- und Messages-Lesevorgänge. Das Architekturdiagramm zeigt die Verzweigung.

• Kontaktanreicherung über Tools hinweg. Eine gemeinsame Schicht löst rohe Telefonnummern und E-Mail-Adressen in Kontaktnamen auf, über Messages, Mail und Calendar hinweg. Massen-Cache über den SQLite-Adressbuchspeicher, unter 50 ms für 1.100 Einträge; gezielte Nachschläge über JXA whose(). Siehe ADR-002.

• Vorabprüfung. macos-mcp --check validiert macOS-Version, Node.js, das EventKit-Binary, Vollzugriff auf die Festplatte und JXA-Berechtigungen vor der Laufzeit, mit Deep-Links zu den relevanten Systemeinstellungen für alles, was fehlschlägt.

Einrichtung

Voraussetzungen

• Node.js 20+

• macOS

• Xcode Command Line Tools (Swift-Kompilierung)

Client-Konfiguration

Die JSON-Konfiguration ist für alle Clients gleich. Nur der Speicherort unterscheidet sich.

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": ["mcp-macos"]
    }
  }
}

Berechtigungen

macOS fragt beim ersten Gebrauch nach Zugriff. Klicken Sie auf Erlauben, wenn Sie dazu aufgefordert werden.

Messages und Mail lesen SQLite-Datenbanken direkt, daher benötigt Ihre Terminal-App (Terminal, iTerm2 usw.) Vollzugriff auf die Festplatte.

Führen Sie macos-mcp --check aus, um zu überprüfen. Siehe Fehlerbehebung, wenn etwas fehlschlägt.

Fehlerbehebung

Schnellkorrektur-Befehle

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Vollzugriff auf die Festplatte (Messages & Mail)

Messages und Mail lesen SQLite-Datenbanken (~/Library/Messages/chat.db und ~/Library/Mail/V10/MailData/Envelope Index). Diese erfordern Vollzugriff auf die Festplatte für Ihre Terminal-App.

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Benutzer von Versionsverwaltungen (Volta, nvm, fnm): Der node-Befehl ist ein Shim. Die Systemeinstellungen benötigen das echte Binary:

Die Systemeinstellungen zeigen möglicherweise keine Binaries in versteckten Verzeichnissen an. Verwenden Sie open -R oben, um es im Finder anzuzeigen, und ziehen Sie es dann in die FDA-Liste.

JXA-Automatisierung (Notes, Mail, Contacts)

Beim ersten Gebrauch fragt macOS nach Automatisierungszugriff. Gewähren Sie ihn über Systemeinstellungen > Datenschutz & Sicherheit > Automatisierung.

Berechtigungen überprüfen:

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

Jeder Befehl sollte einen Wert zurückgeben. Ein Hängenbleiben bedeutet, dass der Berechtigungsdialog versucht (und scheitert), zu erscheinen.

Gmail-Labels / Fehlende Posteingangsnachrichten

Gmail speichert alle Nachrichten in [Gmail]/All Mail und verwendet Labels für die Ordnerzugehörigkeit. Der Server prüft sowohl das direkte Postfach als auch die Labels-Join-Tabelle. Wenn Gmail-Posteingangsnachrichten fehlen, stellen Sie sicher, dass die Mail-App vollständig synchronisiert ist.

Entwicklung

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

Der Produktionseinstiegspunkt (bin/run.cjs) erfordert pnpm build. Verwenden Sie pnpm dev für die lokale Entwicklung.

Architektur

flowchart LR
    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]

Drei Brücken zu Apple-Apps:

• EventKit (Swift-Binary). Reminders, Calendar. Kompiliertes Swift-CLI, gibt JSON zurück.

• JXA. Notes, Mail-Schreibvorgänge, Contacts. Skripte, die über osascript -l JavaScript ausgeführt werden.

• SQLite. Messages-Lesevorgänge (~/Library/Messages/chat.db), Mail-Lesevorgänge (~/Library/Mail/V10/MailData/Envelope Index). JXA-Nachrichtenlesen ist unter Sonoma und später defekt. JXA-Mail-Lesen ist für echte Posteingänge zu langsam.

Mail und Messages verwenden einen Hybridpfad: JXA für Schreibvorgänge (einzige Möglichkeit, Senden/Entwurf auszulösen), SQLite für Lesevorgänge (die einzige Möglichkeit, die skaliert). Siehe DECISION.md für Architektur-Entscheidungsprotokolle.

Abhängigkeiten

Laufzeit: @modelcontextprotocol/sdk, zod

Entwicklung: typescript, tsx, jest, @biomejs/biome

Danksagungen

Die MCP-Server-Schicht stammt von FradSer/mcp-server-apple-events (MIT). Das EventKit-Swift-CLI, die SQLite-Lesepfade, die Kontaktanreicherung, die Vorabprüfung und die Fähigkeitsoberfläche wurden hier hinzugefügt.

Lizenz

MIT

Mitwirken

Siehe CONTRIBUTING.md.