Apple Mail MCP Server

Ein MCP-Server, der programmatischen Zugriff auf Apple Mail bietet und KI-Assistenten wie Claude ermöglicht, E-Mails unter macOS zu lesen, zu senden, zu durchsuchen und zu verwalten.

⚠️ Pre-1.0 — Breaking Changes sind zu erwarten. Die MCP-Tool-Oberfläche (Toolnamen, Parameter, Rückgabeformen) entwickelt sich weiter, während das Projekt reift. Fixieren Sie eine bestimmte Version (z. B. apple-mail-mcp==0.8.1) und lesen Sie die CHANGELOG, bevor Sie aktualisieren.

Tools (23)

Kern: list_mailboxes, search_messages, get_messages, update_message Lebenszyklus von Entwürfen: create_draft, update_draft, delete_draft Mailbox-CRUD: create_mailbox, update_mailbox, delete_mailbox Anhänge & Verwaltung: save_attachments, delete_messages Ermittlung & Regeln: list_accounts, list_rules, get_thread, create_rule, update_rule, delete_rule Vorlagen: list_templates, get_template, save_template, delete_template, render_template

Die vollständige Parameter- und Rückgabeform-Dokumentation 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 eingerichteten Konto

• uv (empfohlen) oder pip

Installation

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

Konfiguration

Fügen Sie Ihre Claude-Desktop-Konfiguration (~/Library/Application Support/Claude/claude_desktop_config.json) hinzu:

{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}

Berechtigungen

Beim ersten Start fordert macOS den Automatisierungszugriff an. Erteilen Sie die Berechtigung unter: Systemeinstellungen > Datenschutz & Sicherheit > Automatisierung > Terminal (oder Ihre IDE)

Optional: schnellere Suche über IMAP

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

So funktioniert es. Wenn für ein Konto ein Keychain-Eintrag vorhanden ist, verwendet der Server IMAP (schnelle, serverseitiges SEARCH). Anderfalls — oder bei einem beliebigen IMAP-Fehler (offline, falsches Passwort, Zeitüberschreitung) — wird ohne Vorwarnung auf AppleScript zurückgegriffen. Sie verlieren keine Funktionalität; Sie gewinnen nur Geschwindigkeit, wenn IMAP konfiguriert und erreichbar ist. Keine Konfigurationsflags, keine Umgebungsvariablen – nur die Anwesenheit der Keychain-Eintrags ist das Opt-in.

Einmalige Einrichtung pro Konto.

1. Erzeugen Sie ein App-spezifisches Passwort bei Ihrem Anbieter. Die Vorgehensweise 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 zweistufige Verifizierung auf Ihrem Google-Konto.

   • Yahoo / Fastmail / AOL: Erzeugen Sie ein App-Passwort in der Kontosicherheits-Einstellung des Anbieters.

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

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

   Verwenden Sie den Kontonamen der Mail.app genau so, wie er in Mail.app bezeichnet ist (z.B. iCloud, Gmail, "Yahoo!"). Die CLI:

   • liest die primäre E-Mail-Adresse des Kontos aus Mail.app (mittels --email zusätzliche Angabe),

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

   • schreibt in den Keychain unter apple-mail-mcp.imap.<account> (idempotent — die Wiederverrundung mit einem neuen Passwort aktualisiert den vorhandenen Eintrag),

   • öffnet eine IMAP-Verbindung und führt eine echte LOGIN-Prüfung durch, um zu bestätigen, dass das Passwort funktioniert. Bei Absackern wird der Keychain-Eintrag rückgängig gemacht, damit Sie es erneut versuchen können, ohne ein defektes Eintrag zu begeben.

3. Wenn beim nächsten IMAP-basierten Aufruf eine einmalige Aufforderung „Sicherheit möchte den »login«-Schlüsselbund verwenden“ angezeigt wird, klicken Sie auf Immer erlauben.

Später kann den Eintrag wie folgt entfernen: apple-mail-mcp setup-imap --account iCloud --uninstall.

Überprüfung der Einrichtung. Der Befehl setup-imap führt diese Prüfung automatisch durch. Falls Sie eine Stichprobe nachträglich durchführen wollen:

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

Wenn IMAP funktioniert, erfolgt die Antwort in ~1 Sekunde. Falls eine WARNUNG zum Fallback protokolliert wird (sichtbar mit --log-level=DEBUG), überprüfen Sie, ob der Kontonamen in genau mit dem in Mail.app übereinstimmen und die E-Mail-Adresse in Ihrem Keychain-Eintrag genau dem entspricht, was email addresses of account zurückgibt.

Bekannte Anbieter-Besonderheiten.

• iCloud: Der IMAP-Server akzeptiert @icloud.com / @me.com Aliases als LOGIN-Benutzernamen, nicht die Apple-ID-E-Mail. Der Server (und setup-imap) liest deshalb email addresses of account aus Mail.app heraus.

• Yahoo: App-Passwörter wurden zunehmend abgekündigt; diese Option könnte für einige Konten nicht verfügbar sein. Wenn die Yahoo-Kontosicherheitsseite die Option nicht anzeigt, ist eine IMAP-Einrichtung für dieses Konto nicht möglich und AppleScript ist der einzige Weg.

• Gmail: Erfordert eine aktivierte zweistufige Verifizierung. Wenn Ihr Google-Workspace-Administrator App-Passwörter auf Mandantenfebene deaktiviert hat, ist eine IMAP-Einrichtung für dieses Konto nicht möglich.

• Gmail-Thread-Abruf — Kompromiss bei der Sichtbarkeit von All Mail: find_thread_members (intern von thread-bewussten Abfragen verwendet) ist ein Standort, wenn [Gmail]/All Mail für IMAP freigeschaltet ist — dieser Pfad benötigt ~5 Roundtrips, unabhängig von der Postfachanzahl. Viele Nutzer blenden All Mail aus (Gmail Einstellungen → Weiterreibung und POP/IMAP → Ordner-Limitgrößen → „Do not show in IMAP“), weil jede Nachricht dupliziert wird. Wenn All Mail ausgeblendet ist, setzt die Konnektor auf eine wiederholte Über X-GM-THRID pro Postfach zurück (immer noch ~6× schneller als die universelle BFS, aber abhängig von Ihrer Labelzahl — ~25 Sekunden bei einem 92-Label-Konto). Schalten Sie All Mail sichtbar ein, wenn Sie die maximale Geschwindigkeit möchten; lassen Sie es ausgeblendet, wenn Sie eine übersichtlichere IMAP-Ordnerliste bevorzugen.

Schreibvorgängen (create_draft, update_draft, einschließlich des send_now=true Send-Pfads) verwenden unabhängig von der IMAP-Konfiguration immer AppleScript — sie benötigen man die Komformationsoberfläche der Apple Mail.

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)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app

• server.py — Registrierung der MCP-Tools, Eingabevalidierung, Antwortformatierung

• mail_connector.py — Gesamte AppleScript-Erzeugung und -Ausführung

• security.py — Bereinigung des Eingabe, Audit-Logging, Bestätigungsabläufe

• utils.py — Verfeinerte Funktion: Strictionsvermögen, Escaping, Parsen, Validierung

• exceptions.py — Typisierte Exception-Hierarchie

Sicherheit

• Nur lokale Ausführung (keine Verarbeitung in der Cloud)

• Verwendet die bestehende Apple Mail-Authentifizierung (keine Speicherung von Anmeldedaten)

• Alle Eingaben werden bereinigt und für AppleScript maskiert

• Destruktive Vorgänge erfordern eine Bestätigung

• Audit-Logging von Vorgängen

• Siehe SECURITY.md für die Richtlinie und docs/SECURITY.md für die detaillierte Analyse

Beiträge

Siehe CONTRIBUTING.md für die Entwicklungsworkflows, Codierungsstandards und den Pull-Request Prozess.

License

MIT