Apple Mail MCP Server

Ein MCP-Server, der programmatischen Zugriff auf Apple Mail bietet und KI-Assistenten wie Claude das Lesen, Senden, Suchen und Verwalten von E-Mails unter macOS ermöglicht.

⚠️ Vor 1.0 – es sind breaking changes zu erwarten. Die MCP-Tool-Oberfläche (Tool-Namen, Parameter, Rückgabestrukturen) entwickelt sich mit dem Projekt noch weiter. Fixieren Sie eine bestimmte Version (z. B. apple-mail-mcp==0.10.2) und prüfen Sie vor einem Upgrade den CHANGELOG.

Werkzeuge (29)

Gruppiert nach Lebenszyklus (10 schreibgeschützt, 19 verändernd):

• Erkennung — list_accounts, list_mailboxes, list_rules, list_templates: listet auf, was konfiguriert ist (kein externer Cache – pro Konto aufrufen).

• Lesen — search_messages, get_messages, get_thread, get_attachment_content, get_template, render_template: Nachrichten/Threads lesen, den Inhalt eines Anhangs inline abrufen und Vorlagen rendern.

• Nachrichtenaktionen — update_message (lesen/kennzeichnen/verschieben in einem Durchgang), delete_messages (→ Papierkorb), save_attachments (auf Datenträger, byte-begrenzt).

• Entwürfe — create_draft (neu / antworten / weiterleiten, optional send_now), update_draft, delete_draft.

• Direktes Senden — send_email, reply, reply_all, forward: in einem einzigen Aufruf senden, ohne einen Entwurf zu durchlaufen. Jeder sendet tatsächlich; es gibt keinen zweiten Bestätigungsschritt in Mail.

• Konten — delete_account: ein konfiguriertes Konto aus Mail.app entfernen.

• Postfach-CRUD — create_mailbox, update_mailbox (umbenennen oder verschieben), delete_mailbox.

• Regeln — create_rule, update_rule, delete_rule.

• Vorlagen (Schreiben) — save_template, delete_template.

Destruktive Operationen (delete_*, create_rule mit Verschieben/Weiterleiten/Löschen-Aktionen, create_draft mit send_now=true) fordern über MCP-Elicitation eine Bestätigung an. Vollständige Parameter und Rückgabestrukturen finden Sie in docs/reference/TOOLS.md.

Related MCP server: apple-mail-mcp

Voraussetzungen

• macOS 10.15 (Catalina) oder neuer

• Python 3.10 oder neuer

• Apple Mail mit mindestens einem konfigurierten Konto

• uv (empfohlen) oder pip

Installation

# From source (recommended for development)
git clone https://github.com/LeChabrax/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

Konfiguration

Fügen Sie Folgendes zu Ihrer Claude-Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json). uv sync installiert ein Konsolenskript unter .venv/bin/apple-mail-mcp; weisen Sie Claude Desktop auf dessen absoluten Pfad – das ist die zuverlässigste Form in der eingeschränkten Spawn-Umgebung von Claude Desktop (keine Abhängigkeit von uv im PATH):

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

(Äquivalente Alternative, wenn Sie es lieber über uv ausführen möchten: "command": "uv", "args": ["--directory", "/path/to/apple-mail-mcp", "run", "apple-mail-mcp"].)

Optional: Lese-/Schreib-Server aufteilen

Claude Desktop fragt pro Tool nach der Berechtigung. Wenn Sie die 10 Lese-Tools (list / search / get) in einem Rutsch genehmigen und die 19 verändernden Tools weiterhin einzeln absichern möchten, führen Sie den Connector zweimal aus – einmal mit --read-only, einmal ohne – unter zwei separaten mcpServers-Einträgen:

{
  "mcpServers": {
    "apple-mail-read": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp",
      "args": ["--read-only"]
    },
    "apple-mail-write": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

Der --read-only-Server stellt nur die 10 Lese-Tools bereit, sodass die Berechtigungs-UI von Claude Desktop sie natürlich gruppiert. Der vollständige Server sichert Schreibvorgänge weiterhin einzeln ab. Abwägung: 2× Connector-Prozesse. Siehe docs/reference/TOOLS.md für die Klassifizierung pro Tool und einen Hinweis zu MCP-Annotationshinweisen (readOnlyHint / destructiveHint / idempotentHint), die vorwärtskompatible Hosts verwenden können, um dieselbe Benutzererfahrung ohne die Aufteilung zu bieten.

Berechtigungen

Beim ersten Start fordert macOS Zugriff auf Automatisierung an. Gewähren Sie die Berechtigung unter: Systemeinstellungen > Datenschutz & Sicherheit > Automatisierung > Terminal (oder Ihre IDE)

Optional: Schnellere Suche über IMAP

search_messages funktioniert standardmäßig über AppleScript. Bei großen Postfächern (tausende Nachrichten) kann die whose-Klausel von AppleScript 1–5 Sekunden pro Abfrage dauern. Wenn Sie eine schnellere serverseitige Suche wünschen, können Sie die IMAP-Delegierung pro Konto aktivieren, indem Sie einen Schlüsselbund-Eintrag hinzufügen.

So funktioniert es. Wenn für ein Konto Anmeldedaten vorhanden sind, verwendet der Server IMAP (schnelle serverseitige SEARCH). Andernfalls – oder bei jedem IMAP-Fehler (offline, falsches Passwort, Zeitüberschreitung) – fällt er still auf AppleScript zurück. Sie verlieren nie Funktionalität; Sie gewinnen nur an Geschwindigkeit, wenn IMAP konfiguriert und erreichbar ist. Der normale Opt-in ist ein Schlüsselbund-Eintrag (unten); ein Fallback über Umgebungsvariablen (weiter unten) deckt Kontexte ab, in denen der Schlüsselbund nicht nutzbar ist.

Einmalige Einrichtung pro Konto.

1. Generieren Sie ein app-spezifisches Passwort bei Ihrem Anbieter. Das Vorgehen variiert:

   • iCloud: appleid.apple.com/account/manage → App-spezifische Passwörter. Erfordert 2FA auf Ihrer Apple-ID (Standard).

   • Gmail: myaccount.google.com/apppasswords. Erfordert die Bestätigung in zwei Schritten auf Ihrem Google-Konto.

   • Yahoo / Fastmail / AOL: Generieren Sie ein App-Passwort in den Kontosicherheitseinstellungen des Anbieters.

2. Führen Sie den Unterbefehl setup-imap aus. Er fragt nach dem Passwort (ohne Echo), schreibt den Schlüsselbund-Eintrag und verifiziert durch eine Verbindung:

   apple-mail-mcp setup-imap --account iCloud

   Ersetzen Sie den Kontonamen von Mail.app exakt – wie auch immer er in Mail.app beschriftet ist (z. B. iCloud, Gmail, "Yahoo!"). Die CLI:

   • ermittelt die primäre E-Mail-Adresse des Kontos aus Mail.app (überschreibbar mit --email, was persistiert wird, sodass die Laufzeit denselben Login verwendet – siehe den iCloud-Sonderfall unten),

   • fragt über getpass ab, sodass das Passwort nie in der Shell-Historie landet,

   • schreibt in den Schlüsselbund unter apple-mail-mcp.imap.<account> (idempotent – erneutes Ausführen mit einem neuen Passwort aktualisiert den vorhandenen Eintrag),

   • öffnet eine IMAP-Verbindung und führt einen echten LOGIN durch, um zu bestätigen, dass das Passwort funktioniert. Bei Ablehnung wird der Schlüsselbund-Eintrag zurückgerollt, sodass Sie es erneut versuchen können, ohne ein defektes Element zu hinterlassen.

3. Wenn beim nächsten IMAP-gestützten Aufruf eine einmalige Aufforderung „Sicherheit möchte den Schlüsselbund ‚login‘ verwenden“ erscheint, klicken Sie auf Immer erlauben.

Um den Eintrag später zu entfernen: apple-mail-mcp setup-imap --account iCloud --uninstall.

Fallback über Umgebungsvariablen (uvx / headless / CI)

Manche Kontexte haben keinen nutzbaren Schlüsselbund: uvx-Ausführungen (ephemere Binärpfade brechen die Schlüsselbund-ACL, was zu erneuten Aufforderungen oder Fehlern führt), Docker / CI (kein Schlüsselbund) und Hintergrunddienste (die ACL-Aufforderung blockiert endlos ohne UI). Für diese können Sie das IMAP-Passwort stattdessen über eine Umgebungsvariable bereitstellen:

APPLE_MAIL_MCP_IMAP_PASSWORD_<SUFFIX>

<SUFFIX> ist der Kontoname von Mail.app in Großbuchstaben, wobei jede Folge nicht-alphanumerischer Zeichen zu einem einzelnen Unterstrich zusammengefasst und führende/abschließende Unterstriche entfernt werden:

Wenn auf einen nicht-leeren Wert gesetzt, wird die Umgebungsvariable gegenüber jedem Schlüsselbund-Eintrag für dieses Konto bevorzugt (sie wird zuerst geprüft, ohne security-Shell-Aufruf). Ein leerer oder nur aus Leerzeichen bestehender Wert wird ignoriert und der Schlüsselbund-Pfad verwendet. Die Suche kombiniert sich mit dem Name↔UUID-Fallback, sodass eine auf den Kontonamen abgestimmte Umgebungsvariable auch dann gefunden wird, wenn ein Aufrufer die UUID des Kontos übergibt.

⚠️ Sicherheitsabwägung. Umgebungsvariablen sind weit weniger privat als der Schlüsselbund – sie sind über ps -E, launchctl getenv, /proc-artige Introspection und Prozess-Crash-Dumps sichtbar und können leicht in Logs oder die Shell-Historie gelangen. Verwenden Sie dies nur, wenn der Schlüsselbund wirklich keine Option ist (uvx, Docker, CI, headless). Für Claude Desktop und standardmäßige lokale Installationen bleiben Sie bei setup-imap + Schlüsselbund.

Hinweis: Die Name→Suffix-Zuordnung ist nicht umkehrbar – Yahoo! und Yahoo bilden beide auf YAHOO ab, und ein Kontoname ohne ASCII-Buchstaben/Ziffern hat keine Umgebungsvariablen-Form (verwenden Sie für diese den Schlüsselbund).

Überprüfung der Einrichtung. Der Befehl setup-imap erledigt das für Sie. Wenn Sie nachträglich stichprobenartig prüfen möchten:

uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

Wenn IMAP funktioniert, liefert der Aufruf in ~1 Sekunde ein Ergebnis. Wenn er eine WARNUNG über den Fallback protokolliert (sichtbar mit --log-level=DEBUG), prüfen Sie, ob der Kontoname exakt mit dem Kontonamen in Mail.app übereinstimmt und ob die E-Mail in Ihrem Schlüsselbund-Eintrag dem entspricht, was email addresses of account zurückgibt.

Bekannte Anbieter-Besonderheiten.

• iCloud: Der IMAP-Server akzeptiert @icloud.com / @me.com-Aliasse als LOGIN-Benutzernamen, nicht die Apple-ID-E-Mail. Der Server (und setup-imap) liest aus diesem Grund email addresses of account aus Mail.app. Wenn Ihre iCloud-Apple-ID eine Drittanbieter-Adresse ist (z. B. eine @gmail.com-Apple-ID) und Mail.app keine @icloud.com-Adresse für das Konto meldet, kann die automatische Erkennung den richtigen Login nicht finden – setup-imap schlägt dann mit einem Hinweis fehl, es erneut mit --email <Ihre @icloud.com/@me.com-Adresse> auszuführen. Dieser --email-Wert wird persistiert (in ~/.apple_mail_mcp/imap_login_overrides.json), sodass die Laufzeitauflösung denselben Login verwendet (#341). Es ist eine allgemeine Überschreibung – verwenden Sie sie für jedes Konto, dessen automatisch erkannter IMAP-Login falsch ist.

• Yahoo: App-Passwörter wurden schrittweise abgeschafft; die Option ist möglicherweise nicht für alle Konten verfügbar. Wenn die Kontosicherheitsseite von Yahoo die Option nicht anzeigt, ist eine IMAP-Einrichtung für dieses Konto nicht möglich und AppleScript ist der einzige Weg.

• Gmail: Erfordert die Bestätigung in zwei Schritten. Wenn Ihr Google-Workspace-Administrator App-Passwörter auf Mandantenebene deaktiviert hat, ist eine IMAP-Einrichtung für dieses Konto nicht möglich.

• Gmail-Thread-Abruf – All Mail-Sichtbarkeitsabwägung. find_thread_members (intern von thread-bewussten Abfragen verwendet) ist am schnellsten, wenn [Gmail]/All Mail über IMAP verfügbar ist – dieser Pfad benötigt ~5 Round-Trips, unabhängig von der Postfachanzahl. Viele Benutzer blenden All Mail aus (Gmail-Einstellungen → Weiterleitung und POP/IMAP → Ordnerlimit → „Nicht in IMAP anzeigen“), weil es jede Nachricht dupliziert. Wenn ausgeblendet, fällt der Connector auf eine X-GM-THRID-Iteration pro Postfach zurück (immer noch ~6× schneller als die universelle BFS, aber proportional zur Anzahl Ihrer Labels – ~25s bei einem Konto mit 92 Labels). Blenden Sie All Mail ein, wenn Sie die Spitzengeschwindigkeit wünschen; lassen Sie es ausgeblendet, wenn Sie die sauberere IMAP-Ordnerliste bevorzugen.

Schreiboperationen (create_draft, update_draft, einschließlich des send_now=true-Sendepfads) verwenden unabhängig von der IMAP-Konfiguration immer AppleScript – diese benötigen die Compose-UI von Mail.app.

Zeitüberschreitungen bei sehr großen Postfächern

Die Standardwerte sind für gewöhnliche Postfächer ausgelegt und sollten bei einem großen Postfach erhöht werden. Die eigene Messung dieses Moduls beträgt 148s für 100 Nachrichten mit kaltem Cache in einem Postfach mit 47k Nachrichten, sodass eine serverseitige SEARCH dort das 30s-Standardlimit überschreiten und still auf den langsameren AppleScript-Pfad zurückfallen kann.

Ein nicht-numerischer oder nicht-positiver Wert wird mit einer Warnung ignoriert und der Standardwert beibehalten, sodass ein Tippfehler den Server nicht lahmlegen kann.

Entwicklung

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

Branch-Konvention

{type}/issue-{num}-{description} – z. B. feature/issue-42-thread-support

Architektur

server.py (FastMCP tools — thin orchestration, validation, elicitation gates)
  -> mail_connector.py (dispatch + domain logic)
     -> AppleScript path:  subprocess.run(["osascript", ...]) -> Apple Mail.app   (universal baseline)
     -> IMAP fast path:    imap_connector.py -> the account's IMAP server          (when hinted + Keychain creds)

Dispatch-Modell. AppleScript ist die immer verfügbare Basislinie. Wenn ein Lese-/Änderungsaufruf einen account- (und, wo relevant, mailbox-) Hinweis liefert und das Konto IMAP-Anmeldedaten im Schlüsselbund hat, nimmt der Connector einen serverseitigen IMAP-Schnellpfad; bei jedem IMAP-Fehler fällt er auf AppleScript zurück, sodass Sie nie Funktionalität verlieren – Sie gewinnen nur an Geschwindigkeit. Siehe docs/reference/ARCHITECTURE.md für das vollständige Dispatch-Modell, das Dual-Emit-Nachrichten-ID-Schema, den Entwurfslebenszyklus und die IMAP-Thread-Ebenen.

• server.py — MCP-Tool-Registrierung, Eingabevalidierung, Bestätigungs- (Elicitation-) Gates, Antwortformatierung

• mail_connector.py — AppleScript-Erzeugung/-Ausführung + IMAP-Schnellpfad-Dispatch

• imap_connector.py — IMAP-Client + Verbindungspool (Such-, Abruf-, Massenänderungs-Schnellpfade)

• security.py — Eingabebereinigung, Audit-Protokollierung, Bestätigungsabläufe

• utils.py — Reine Funktionen: Escaping, Parsing, Validierung

• exceptions.py — Typisierte Ausnahmehierarchie

Sicherheit

• Nur lokale Ausführung (keine Cloud-Verarbeitung)

• Verwendet die vorhandene Mail.app-Authentifizierung; IMAP-App-Passwörter (optional) liegen im macOS-Schlüsselbund, nie im Repository oder in der Konfiguration

• Alle Eingaben werden bereinigt und AppleScript-escaped (Schutz gegen AppleScript-Injection)

• Destruktive Operationen erfordern Benutzerbestätigung über MCP-Elicitation; zusätzlich Ratenbegrenzung und Audit-Protokollierung

• save_attachments ist byte-begrenzt (pro Anhang + aggregiert) gegen Disk-Fill-DoS

Dokumentation:

• SECURITY.md — Richtlinie zur Meldung von Schwachstellen

• docs/SECURITY.md — Benutzerorientierte Sicherheitslage & Datenschutz

• docs/guides/THREAT_MODEL.md — STRIDE-Vertrauensgrenzen-Analyse

• docs/guides/SECURITY_CHECKLIST.md — Mitwirkenden-Checkliste pro Funktion

Mitwirken

Siehe CONTRIBUTING.md für den Entwicklungsablauf, Codierungsstandards und den PR-Prozess.

Danksagungen

Dieses Projekt ist ein Fork von apple-mail-mcp von Morgan Jeffries, das die gesamte schwere Arbeit leistet: die AppleScript-Brücke, den IMAP-Schnellpfad, den Entwurfszustandsspeicher, die Vorlagen und die Elicitation-Gates.

Was dieser Fork zusätzlich zu Upstream v0.10.2 bietet:

Alles andere, einschließlich der Tool-Oberfläche, der Tests und der Dokumentation, stammt von Upstream. Fehlerberichte zu den gemeinsamen Teilen werden besser dort eingereicht.

Was Mail.app diesem Server nicht erlaubt

Gemessen auf macOS 15, wissenswert vor dem Öffnen eines Issues:

• Ein über AppleScript erstelltes Konto wird nie dauerhaft gespeichert. make new imap account gibt eine ID zurück und count of accounts sieht es, aber es fehlt im Einstellungsfenster von Mail und ist verschwunden, sobald Mail beendet wird. Das Hinzufügen eines Kontos für echt erfordert ein Konfigurationsprofil (com.apple.mail.managed), das auf dem Bildschirm genehmigt wird. Es gibt keinen skriptbaren Weg: profiles install antwortet mit "profiles tool no longer supports installs".

• enabled kann bei keinem Konto geschrieben werden. set enabled wirft -10000 AppleEvent handler failed, bei einem neuen Konto und bei einem bestehenden aktiven, über AppleScript und über JXA, mit jeder Referenzform. Mails eigene sdef deklariert die Eigenschaft als schreibbar (kein access="r", Cocoa-Schlüssel isActive); die Implementierung widerspricht.

• Das Einstellungsfenster von Mail ist eine veraltete Momentaufnahme. Es listet Konten auf, die AppleScript nicht mehr kennt, und lässt solche aus, die es kennt. Lesen Sie den Kontostatus niemals aus der Benutzeroberfläche.

Lizenz

MIT