che-apple-mail-mcp

Der umfassendste Apple-Mail-MCP-Server – 53 Tools mit SQLite-basierter Millisekundensuche über 250.000+ E-Mails.

English | 繁體中文

Warum che-apple-mail-mcp?

Related MCP server: apple-mail-mcp

Schnellstart

Installieren Sie das Plugin. Es bringt die signierte Binärdatei, die Befehlsfamilie /archive-mail, die Sicherheitsregeln und den Staleness-Hook als eine Einheit mit:

claude plugin marketplace add PsychQuant/che-apple-mail-mcp
claude plugin install che-apple-mail-mcp@che-apple-mail-mcp

Erteilen Sie dann die Berechtigungen – das Einrichtungsfenster zeigt den Live-Status und verlinkt direkt zum richtigen Bereich der Systemeinstellungen:

~/bin/CheAppleMailMCP --setup

💡 Full Disk Access ist das, was den schnellen SQLite-Lesepfad und batch_export_emails_markdown ermöglicht. Ohne diese Berechtigung laufen die Tools zwar weiter, lesen aber kaum oder gar nichts – das wird leicht für einen Fehler gehalten, statt für eine fehlende Berechtigung. macOS erlaubt es einer App nicht, FDA programmatisch anzufordern; sie muss von Hand aktiviert werden, wofür das Einrichtungsfenster genau da ist.

Plugin vs. MCP-only

Die alleinige Registrierung des MCP-Servers ist ein unterstützender, erweiterter Pfad, aber er ist eine deutlich kleinere Installation. Wählen Sie es bewusst – nichts wird zur Laufzeit darauf aufherezu #353):

git clone https://github.com/PsychQuant/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

# --scope user     : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --               : separator between claude options and the command
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

Installieren Sie die Binärdatei in ein lokales Verzeichnis wie ~/bin/. Vermeiden Sie cloud-synchronisierte Ordner (Dropbox, iCloud, OneDrive) – Synchronisationsaktivitäten führen zu MCP-Verbindungszeitüberschreitungen.

Damit eine selbstgestrickte Binärdatei ihre TCC-Berechtigungen über Neuerungen hinweg behält, signieren Sie sie mit einer Developer ID; siehe Signing & Notarization. Andernfalls müssen Sie damit rechnen, die Berechtigungen nach jedem Build neu zu erteilen.

Die aktuellen Releases

Ausführliche Details finden Sie in CHANGELOG.md.

v2.7.2 (2026-05-10) – attachmentFragment-Cluster + Fallback-Parität

• attachment. Das Einrücken von attachmentFragment wird in allen drei Callern gestärkt; zusätzlich wird die Jean MailController.attachmentScript entfernt, die die Race-Abschwächungsverzögerung von v2.7.0 umging (#61, #62).

• Begrenzung der Anhänge (50) + umgebungskonfigurierbare Verzögerungen über CHE_MAIL_ATTACHMENT_DELAY_BETWEEN / _TRAILING (#63, #75).

• Der SQLite-Pfad von get_email_metadata fällt bei Fehlern jetzt auf AppleScript zurück – die letzte Lücke bei den Lesetools ist geschlossen; All 8 SQLite-Tools ohne "Fallback" haben jetzt "Fallback-Parität" (#71).

v2.7.1 (2026-05-09) –‑ base64-Fix + .partial.emlx + Beobachtbarkeit

• Kritisch: Der UDPHeader/Body-Teil gab einen relativen statt einem absoluten Data-Index zurück, und der Beginn von html_body mit „sion: 1.0\n\n<base64>" – bei einigen Android-Gmail-Nachrichten wurde der rohe base64 in den LLM-Kontext eingesikt und verursachte Follow-up AUP-Fehl─#72).

• save_attachment liest nun den Vorcache Attachments/<rowId>/<part_id>/<filename> aus, wenn der .partial.emlx body leer ist – keine stummen 0-Byte-Schr Stud für IMAP-Nachrichten mit entfernten Binäranhängen (#66).

• SQLite-Fehler im Schnellpfütze werden jetzt auf stderr protokolliert (SQLite ... fast path failed for rowId=...; falling through to AppleScript) (#69).

v2.7.0 (2026-05-04) – Mail.app Race-Entwurf

• Multi-Anhang-AppleScript wirkt mit 0,3 s zwischenverzögerung und 0,5 s Nachdorferung das stille Verlerren von Anhängen durch Mail.app bei schnellem IPC (#60).

v2.6.0 (2026-05-03) – Sicherheits- und Validierungshärtung (8 PRs, 16 Issues)

• forward_email bettet im Plain-Text-Modus jetzt das RFC 3676 > -Quoting-Original ein (Greatsk); (#44).

• Harte Abbruch bei Parameter-/Typkonflikt – bool und [String] werden nicht mehr still Blender ziehen (#35).

• Die Validierung der Empfänger-E-Mails verwahrnt Header-Injection (Steuerzeichen, fehlendes/mehrgeschlechtiges @ (#41).

• cc_additional divides exceptions (#34).

• Deny-Liste für Anhangspfade (~/.ssh, Keychains, TCC‑DB, Browser-Cookies) + symlink-based + neuer MAIL_MCP_ATTACHMENT_ROOTS-ینvironment allow-list (#38).

• Die 17 Tools, die eine id akzeptieren, validieren id strikt als Int im Handler-Grenz – das verhinderter AppleScript-Prädikateninjection (#50](https://github.com/... )).

• Gated-integrationstests für diereply_email Laufzeit (#37, #45) + Smoke-Matrix-Templates (#46, #47).

v2.3.0 (2026-04-17) – format-Parameter beim Verfassen

• Alle 4 Komponieren-Tools (compose_email / create_draft / reply_email / forward_email) erhalten den Parameter format: "plain" | "markdown" | "html" (schließt #14 und #15).

• Neue message-composition-Capabilities-Spezifikation.

Alle 53 Tools

Beispiel: Antwort als Entwurf (v2.4.0+)

Auf einen Thread antworten, zusätzliche CC-Empfänger hinzufügen, Dateien anhängen und vor dem Senden als Entwurf zur manuellen Prüfung speichern:

reply_email(
    id="<message id from search_emails>",
    mailbox="INBOX",
    account_name="iCloud",
    body="Reply text",
    cc_additional=["x@y.com"],
    attachments=["/path/to/file.pdf"],
    save_as_draft=true
)

Antwortform: search_emails / list_emails

Beide Tools geben ein Envelope-Objekt { results, returned, limit, truncated } zurück — kein bloßes Array (geändert in v2.14.0, #204). Lesen Sie die Treffer aus .results:

truncated ist definitiv auf dem SQLite-Schnellpfad (intern werden limit + 1 Datensätze abgerufen); beim AppleScript-Fallback handelt es sich um eine Best-Effort-Heuristik (returned == limit). Jeder Consument, der nach dem Muster „Aufzählen → Stapelverarbeitung“ vorgeht, sollte truncated prüfen, bevor er annimmt, er hätte den vollständigen Satz.

Installation

Beginnen Sie mit Quick Start — das Installieren des Plugins ist der unterstützte Weg und liefert Ihnen die Befehle, Sicherheitsregeln, eine Staleness-Hook und eine signierte Binärdatei. Alles unten ist der **fortgeschrittene / Entwicklungs-**Weg: Er registriert nur den MCP-Server, was eine strikt kleinere Installation ist (siehe Plugin vs MCP-only für das, was fehlt, da Ihnen nichts zur Laufzeit davon angezeigt wird).

Voraussetzungen

• macOS 13.0+

• Xcode Command Line Tools (für den unten beschriebenen Build-it-yourself-Weg)

• Apple Mail mit mindestens einem eingerichteten Konto

Schritt 1: Build

git clone https://github.com/PsychQuant/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

Schritt 2: Konfigurieren

Für Claude Desktop

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "che-apple-mail-mcp": {
      "command": "/full/path/to/che-apple-mail-mcp/.build/release/CheAppleMailMCP"
    }
  }
}

Für Claude Code (CLI)

# Copy to ~/bin and register (user scope = available in all projects)
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

Schritt 3: Berechtigungen erteilen

Der schnellste Weg ist das Setup-Fenster, das den live-Status von Full Disk Access / Automatisierung / Bedienungshilfen anzeigt, nach dem Gewähren erneut prüft und den richtigen Systemeinstellungsbereich für Sie öffnet:

~/bin/CheAppleMailMCP --setup

Stattdessen manuell vorgehen:

Automatisierung (Steuerung von Mail.app):

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"

1. CheAppleMailMCP suchen und die Berechtigung für Mail.app aktivieren

2. Wenn Sie Claude Code verwenden, fügen Sie außerdem Terminal oder iTerm hinzu

Full Disk Access (der SQLite-Schnellpfad und export_emails_markdown lesen ~/Library/Mail):

open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

macOS gewährt Full Disk Access dem verantwortlichen Prozess — also der App, die diese Server gestartet hat — nicht der Binärdatei selbst. Für einen MCP-Server, der von Claude Code innerhalb eines Terminals ausgeführt wird, ist der verantwortliche Prozess das Terminal (Ghostty / Terminal / iTerm). Fügen Sie daher Ihre Terminal-App hier hinzu und aktivieren Sie ihn. Ein Zugriff auf das Terminal gilt für alle MCP-Server, die es startet. (Wenn Sie die Binärdatei stattdessen direkt ausführen oder das Claude Desktop-Bundle verwenden, fügen Sie die Binärdatei hinzu — ~/bin/CheAppleMailMCP —, da sie dann ihr eigener verantwortlicher Prozess ist.) In der FDA-verweigerten Fehlermeldung werden diese Kandidaten genannt — sie lösen aber nicht die eine genaue App automatisch auf, da macOS dafür keine zuverlässige prozessinterne API bereit hält (#214). Ohne Full Disk Access fallen die Lesewerkzeuge stillschweigend auf den langsameren AppleScript-Pfad zurück und Ergebnisse wie projection, export_emails_markdown schlagen SQLite-only-Frottenheit fehl. Für den direkten Start sel bei mit Developer ID signierter Build erhalten bleiben die Berechtigungen über Versions springe hinweg — siehe Signing & Notarization.

Gelenktes Setup (#213) — Statt der obigen manuellen Schritte enthält die Binär datei Setup-Helfer:

• CheAppleMailMCP --setup öffnet ein kleines Fenster mit Live-Status für Full Disk Access (wird zeitgerecht neu geprüft, schaltet auf „Bereit ✅“, sobald Sie einen Zugriff gewähren) effektiv zusätzlich eine on-demand Automations-Prüfung sowie Schaltflächen „Full Disk Access-Einstellungen öffnen“ / „Binärpfad kopieren“.

• CheAppleMailMCP --check-fda per Ausdruck den Status headless dar (und öffnet dann, wenn der Zugriff verweigert wird) — praktisch in einer Terminal-oder Skript-zeile.

• Das MCP-Tool gibt denselben Status auf Anfrage an Claude weiter (rufen Sie es auf, wenn eine reine SQLite-Funktion Fehler heißt).

Keine dieser Hilfen kann das einmalige Umschalten per Hand ersetzen (Apple legt FDA in die Stufe „nur manuell“ zusammen mit Accessibility / Screen Recording), aber sie machen deutlich, „Was mache ich?“.

Accessibility (Compose, #175/#304) – eine separate, optionale Berechtigung neben dem Full Disk Access. Mail.app umschließt jeden per AppleScript eingefügten Text einer ausgehenden Nachricht in <blockquote type="cite">, den einige mobile Clients als Zitat Ihres eigenen Texts rendern – und den der Absender lokale nicht sehen kann, weil der Inline-Stil des Wrappers keine Umrandung hat. Seit #304 ** besteht der Code, der das erzeugt, nicht mehr**: Jedes Compose-Tool übernimmt seinen Inhalt aus Mails eigenem Editor – eine Übergabe per mailto: für compose_email / create_draft, das native Antworten-/Weiterleiten-Verb plus Einfügen für reply_email / forward_email – und steuert Speichern/Senden/Anhängen über Tastaturkürzel, was Accessibility setzt (System Settings → Privatsphäre-Schutz & Sicherheit → Accessibility) voraus, erteilt an denselben verantwortlichen Prozess wie die FDA (Ihr Terminal bzw. Claude Desktop). Das MCP-Tool check_accessibility und die Accessibility-Zeile im --setup-Fenster melden den Status. Ohne sie schlagen diese Tools jetzt fehl, statt zu einer Fallback – es gibt keinen zweiten Pfad, auf den zurückgegriffen werden kann; ein Aufruf, der nicht sauber ausgeführt werden kann, gibt einen benannten Fehler zurück and erzeugt nichts. Der Fehler verweist auf open_mailto, das keinerlei TCC-Berechtigung braucht (Anhänge kann es nicht übertragen; Sie speichern bzw. senden das Fenster selbst). Genau sechs Bedingungen lehnen einen Aufruf ab: ein format, das nicht plain ist; ein leerer Betreff; nicht erteilte Accessibility; eine from_address, die keine reine addr-spec ist; ein Anhangpfad, der Nicht-ASCII-Zeichen enthält (#220); und ein Empfänger mit Anzeigenamen, den dieser Pfad nicht ausfüllen kann (cc/bcc immer; bei einer gesendeten to – der to-Anzeigename eines Entwurfs wird über die GUI gesetzt, #277). Verwenden Sie für einen sauberen Inhalt bei einem nicht standardmäßigen Konto from_address: Die GUI wählt sie in Mails Von-Popup aus und liest die Zustimmung zurück; Arbeitsgang bricht ab, anstatt den falschen Sender zu riskieren (#219). Mit dem Legacy-Pfad entfernt: format: "markdown" / "html" – kein heute mitgelieferter Pfad liefert Rich Text ohne die Textzuweisung, die gelöscht wurde. Das ist der existierende Zustand, kein Beweis der Unmöglichkeit (#310): Der Einfügepfad (Past-Feld, #218) ist eine zweiteroute ohne Wrapper, und NSPasteboard kann reichhaltige Daten nutzen, aber die erzeugte MIME ist ungeprüft – #306 entscheidet das; #308 / #309 sind Alternativen, die Parameter require_wrapper_free und sanitize_links sowie die CHE_MAIL_DISABLE_MAILTO_COMPOSE- / CHE_MAIL_DISABLE_PASTE_REPLY-Notlüre. Zwei Fähigkeiten entfallen damit, klar gesagt: Das Verfassen ohne sichtbares Fenster (der ursprüngliche Zweck und Notlüsen) ist nicht mehr möglich, und compose_email kann nicht mehr an Name <addr> senden – verwenden Sie create_draft und senden Sie den Entwurf selbst.

Automations-TCC (-1743) und die Zero-TCC-Notluke

Wenn AppleScript-gestützte Tools mit dem Fehler AppleScript error (-1743): Not authorized to send Apple events to Mail fehlschlagen, fehlt die Automation-Berechtigung für dieses Binary. Das signierte MCP-Binary besitzt eine eigene Automation-Berechtigung – seine TCC-Identität ist an die Signativität des Binaries gebunden (die #FDA-Lektion, Automationsachse), also getrennt von der Ihres Terminals. Empirisch bestätigt: osascript, das Mail aus Ihrer Shell steuert, bedeutet nicht, dass das Binary autorisiert ist. Gewähren Sie den Zugriff unter Systemeinstellungen → Datenschutz & Sicherheit → Automation und zeigen Sie auf den Eintrag des Binaries bzw. Claude.app und aktivieren Sie Mail. Enthält keine Eintrag, wird eine frühere Ablehnung gemerkt und macOS fragt nicht erneut: tccutil reset AppleEvents ausführen und dann ein Mail-Tool erneut aufzurufen, um die Daten wiederauszulösen. Berechtigungen gelten pro Installation, und ein Binary-Update kann den Eintrag ungültig machen (#178).

Bis die Berechtigung vorliegt, funktioniert open_mailto weiter: Es läuft über LaunchServices (null TCC, #287) und öffnet ein Fenster ohne Zitatblock im Standard-Mailprogramm des Systems. mailto: vorgesehen keine Anhänge (RFC 6068) – ziehen Sie Dateien manuell hinein.

Schritt 4: Claude neu starten

# For Claude Desktop
osascript -e 'quit app "Claude"' && sleep 2 && open -a "Claude"

# For Claude Code - start a new session
claude

Verwendungsbeispiele

Natürliche Sprache (Claude Desktop)

"List all my mail accounts"
"Show unread emails in Gmail inbox"
"Search for emails about 'quarterly report'"
"Send an email to john@example.com about the meeting"
"Flag important emails in red"
"Create a rule to move newsletters to a folder"

Direkte Tool-Aufrufe (Claude Code)

"Use list_accounts to show my accounts"
"Use search_emails to find emails containing 'invoice'"
"Use set_flag_color to mark email ID 12345 as blue"
"Use check_for_new_mail to refresh"

Flaggen- & Hintergrundfarben

Flaggenfarben (set_flag_color)

Hintergrundfarben (set_background_color)

blue, gray, green, none, orange, purple, red, yellow

Leistung & Speicher

SQLite + .emlx-Schnellpfad

Die meisten Lesetools verwenden lieber den lokalen Envelope-Index (SQLite) von Apple Mail sowie die .emlx-Nachrichtendateien auf der Datenplatte als AppleScript-IPC, mit transparentem AppleScript-Fallback, wenn der SQLite-Pfad eine Anfrage nicht bedienen kann:

Für den Lesepfad von save_attachment ist der Schnellpfad 10–100× schneller als AppleScript (gemessen in #12). Die Beschleunigungsraten der anderen Tools hängen von der Anfrageform ab; allgemein profitieren umfangreiche Massenabfragen am meisten.

Der Schnellpfad erfordert:

• Full Disk Access für den Hostprozess (Systemeinstellungen → Datenschutz & Sicherheit → Vollzugriff auf Festplatte)

• Den lokalen Speicher von Apple Mail unter ~/Library/Mail/V10/...

• Die Nachricht wurde in den lokalen .emlx-Speicher synchronisiert

EWS- / Exchange-Konten umgehen den Schnellpfad bewusst

Exchange-Konten (EWS) in Apple-Mail erzeugen keine .emlx-Dateien – die Nachrichteninhalte liegen auf dem Server und werden bei Bedarf abgerufen. Für diese Konten fallen alle 8 Lesetools (bewerte inklusive get_email_metadata seit #71) transparent auf AppleScript-IPC zurück (das ist korrekt, aber langsamer). Symptome:

• Das Massenladen von 500 EWS-Nachrichten ist deutlich langsamer als 500 IMAP/Gmail-Nachrichten

• Das ist kein Fehler, sondern eine Einschränkung der Apple-Mail-Speicherarchitektur (siehe #9)

Schnellpfad-Umgehung diagnostizieren

Wenn der Schnellpfad für ein Nicht-EWS-Konto fehlschlägt, wird der Fehler auf stderr (seit #69) protokolliert. Starten Sie das Binary in einem Terminal und beobachten Sie stderr, pneumatisch, teilen Sie:

• EnvelopeIndexReader init failed: ... – Datenbank nicht erreichbar (typischerweise: Full Disk Access fehlt)

• SQLite get_email fast path failed for rowId=N: ... – pro Nachricht aufgetretener Ringschluss (z. B. Existenz nur wie .partial4), fehlerhaftes MIME, Datei noch nicht synchronisiert)

In Full beiden Fälle fällt transparent auf AppleScript zurück; in der Protokolltailer anderen bleibt ... falling through to AppleScript erhalten, sodass das Verhalten erhalten bleibt, während die Beobachtbarkeit wiederhergestellt ist.

Fehlerbehebung

Eindeutige Konto-Zuordnung

Der AppleScript-Selektor account "<display_name>" von Mail.app ist nicht eindeutig, wenn zwei Konten denselben display_name verwenden – ein häufiges Muster, wenn ein iCloud-Catch-all-Alias eine Gmail-Adresse an sich selbst weiterleitet oder wenn Google Workspace und privates Gmail sich überlappen. Jedes über AppleScript geroutete Tool (save_attachment-Fallback, get_email, mark_read, usw.) wählt dann nicht deterministisch das falsche Konto → -1728 / -1719-Fehler.

Die Lösung: account_id (die global eindeutige UUID von Mail.app) zusammen mit account_name übergeben. Bei Angabe verwendet save_attachment den Auswahlpfad account id "<UUID>" von Mail.app und umgeht so die Mehrdeutigkeit:

// Tool call: save_attachment with account_id
{
    "id": "273214",
    "mailbox": "[Gmail]/全部郵件",
    "account_name": "alice@example.com",
    "account_id": "C38E0583-47F8-4468-BE70-43155C15549D",  // ← disambiguates
    "attachment_name": "report.pdf",
    "save_path": "/tmp/report.pdf"
}

account_id ermitteln:

• Aus den search_emails-Ergebnissen – jedes Objekt im results-Array (ein SearchResult) führt neben account_name auch ein account_id-Feld mit (befüllt durch Dekodieren der Konto-UUID aus der Authority der SQLite-mailboxes.url über MailboxURL.decode – die Speicherkonvention von Mail.app kodiert die Konto-UUID in der Authority der Mailbox-URL; es gibt kein direktes SELECT mailboxes.account_id). Empfohlen: account_id direkt durchreichen.

• Manuell – ~/Library/Mail/V10/MailData/Signatures/AccountsMap.plist lesen. Die Schlüssel der obersten Ebene sind die UUIDs; der AccountURL-Wert enthält die passende E-Mail-Adresse prozentkodiert in der Authority.

• In AppleScript – tell application "Mail" to get id of every account liefert die Liste der UUIDs.

Rückwärtskompatibilität: account_id ist optional. Wenn es weggelassen (oder leer) wird, fallen die Tools auf den bisherigen Pfad account "<display_name> zurück – Verhalten identisch mit nach #101 – mit einer Ausnahme bei save_attachment (#173): Enthält account_name ein @ (also E-Mail-förmig, wie SQLite-Pfad-Tools wie search_emails ihn ausgeben), sucht save_attachment den Namen zunächst in AccountsMap und wechselt stillschweigend auf den Selektor account id "<UUID>" (der Wechsel wird an stderr protokolliert). Genau ein Treffer → diese UUID; mehrere Konten hinter einer Adresse (iCloud-Catch-all + Gmail) → ein klarer Fehler, der alle Kandidaten auflistet, statt eines rohen l-Y-8-Codes; kein Treffer → der bisherige display_name-Pfad, unverändert. Randfall: Ein Mail-Konto, dessen description legitimerweise ein @ enthält und zufällig der E-Mail-Adresse eines anderen Kontos entspricht, wird jetzt zuerst im E-Mail-Namensraum aufgelöst – account_id explizit übergeben, um den Selektor festzunageln. Die anderen Tools behalten den strikten Fallback von vor #101 (der werkzeugübergreifende Durchgang ist #176).

Geltungsbereich: account_id wird in den AppleScript-gerouteten Tools akzeptiert, die dasselbe E-Mail-Konto referenzieren. Es begann mit save_attachment (#101); der #104-Durchlauf hat dann die 13 Werkzeuge für einzelne Nachrichten / Verschieben / Weiterleitung / Postfächer ergänzt:

• `save 圖

• save_attachmentm...#

• save_attachment (#101) – der Ursprung

• PR-A – 5 Mutationswerkzeuge für einzelne Nachrichten: mark_read, flag_email, set_flag_color, set_background_color, mark_as_junk

• PR-B – 3 Werkzeuge zum Verschieben/Entfernen: move_email, copy_email, delete_email

• PR-C – 3 Nachrichten-Relay-Werkzeuge: reply_email, forward_email, redirect_email

• PR-D – 2 CRUD-Werkzeuge für Postfächer: create_mailbox, delete_mailbox

Der Umfang hat sich seitdem über das #104-Set hinaus erweitert:

• #176 – den E-Mail→UUID-Kernpunkt resolveAccountIdForTool auf alle 14 AppleScript-gerouteten Schreib-Handler ausgeweitet (ein E-Mail-förmiges account_name wird also in den UUID-Selektor aufgelöst, nicht nur ein übergebenes account_id akzeptiert).

• #180 – account_id durch die AppleScript-Fallbacks der Lesewerkzeuge gezogen (list_emails / search_emails / get_email / Header / Quelle / Metadaten / Anhänge / get_unread_count) über resolveMailboxRef / resolveMsgRef (der früher aufgeschobene PR-E ist jetzt erledigt).

• #179 – get_special_mailboxes akzeptiert account_id / account_name für die echten Namen der Spezialpostfächer pro Konto.

• #191 – Die Kontoaktionen check_for_new_mail und synchronize_account haben mit account_id eine Ausweichmöglichkeit erhalten (synchronize_account akzeptiert account_id allein).

Weiterhin nicht von account_id abgedeckt (in Bearbeitung): get_account_info / list_mailboxes (#202).

E-Mail compose_email / create_draft weisen den display_name-Kollisionsfehler nicht auf – sie erzeugen eine neue ausgehende Nachricht, statt vorhandene Mail über ein Konto zu referenzieren, und erzeugen damit nie einen account "<display_name>"-Selektor. Die Absenderauswahl bei mehreren Konten ist jetzt über den optionalen Parameter from_address möglich (#131) – übergeben Sie eine der konfigurierten Mail.app-Adressen (z. B. "alice@example.com" oder RFC-5322-Form "Alice <alice@example.com>"), um den sender der ausgehenden Nachricht festzulegen; ohne Angabe wird das Standardkonto von Mail.app verwendet. list_accounts zeigt die auf dem Mac konfigurierten Adressen.

Kontenübergreifendes Verschieben/Kopieren wird über account_id nicht unterstützt (#129; siehe #127). move_email und copy_email akzeptieren eine einzelne account_id, die sowohl durch den Quell-msgRef als auch durch den Ziel-mailboxRef läuft. Diese architektonische Entscheidung ist korrekt (die Verschiebung bleibt innerhalb eines Kontos, weil der AppleScript-Befehl move msg to <mailboxRef> von Mail.app das Zielpostfach in einem einzigen Kontokontext fordert). Die UI von Mail.app erlaubt das Verschieben zwischen Konten per Ziehen und Ablegen, aber die AppleScript-gerouteten Werkzeuge move_email / copy_email können das nicht nachbilden – ein Aufruf von move_email mit der account_id eines Kontos passt das Ziel-Werkzeug to_mailbox aber gegen ein anderes Konto auflösen soll,stillschweigend das Postfach des falschen Kontos gewählt (falls beide ein solches haben) oder führt zu -1719 "Invalid mailbox index". Wenn Sie eine Kopie des Nachrichteninhalts in einem anderen Konto benötigen, können Sie sie manuell über save_attachment + compose_email rekonstruieren – beachten: Das ist kein echtes Verschieben/Kopieren: Original-Metadaten (Message-ID, Empfangsdatum, Status, Beschriftung) und die Nachrichten-Identität bleiben nicht erhalten.

Technische Details

• Framework: MCP Swift SDK v0.10.0

• Lesepfad: SQLite (Envelope Index) + .emlx-Dateiparser, mit AppleScript-Fallback für EWS / nicht parse bare .emlx-Dateien

• Schreib-/Statuspfad: AppleScript über NSAppleScript

• Transport: stdio

• Plattform: macOS 13.0+ (Ventura und später)

Signierung & Notarisierung

Das verteilte Binary ist Developer ID-signiert und notarisiert, und das ist nicht nur kosmetisch. Der schnelle Lesepfad benötigt vollen Festplattenzugriff (FDA), und macOS TCC bindet eine FDA-Freigabe an das Designated Requirement des Binaries. Bei einem Ad-hoc-Binary ist dieses Requirement der cdhash, sodass jede Versionserhöhung die Freigabe ungültig gemacht hat und Sie das Binary nach jedem Release erneut in die Liste „Voller Festplattenzugriff“ aufnehmen mussten. Eine stabile Developer-ID-Signatur bindet die Freigabe stattdessen an die Signieridentität, sodass sie Versionssprünge übersteht (#211) – diese Signatur, nicht die Notarisierung, liefert die Persistenz.

Die Notarisierung ist für Quarantäne-Startpfade relevant: ein Browser-Download oder die .mcpb-Installation (Claude Desktop), bei dem Gatekeeper das Binary beim ersten Start prüft. Der curl + exec-Weg des Plugin-Wrappers setzt kein Quarantäne-Attribut, sodass Gatekeeper dort nie greift. Wir notarisieren trotzdem, damit das veröffentlichte Release-Asset mit jeder beliebigen Methode sicher einsetzbar ist.

Die erste Freigabe bleibt manuell. FDA (kTCCServiceSystemPolicyAllFiles) hat keine programmatische Anforderungs-API – eine App kann nur einen tiefen Link in der Systemeinstellung liefern. Die Signierung macht diese erste Freigabe dauerhaft, nicht automatisch.

Einmalige Einrichtung (Maintainer)

# 1. Developer ID Application cert in your login keychain (needs an Apple Developer account)
security find-identity -p codesigning -v        # find your identity

# 2. notarytool keychain profile (prompts for an app-specific password — never pass it on the CLI)
xcrun notarytool store-credentials <profile-name> \
  --apple-id <your-apple-id> --team-id <your-team-id>

# 3. Export both for the signed targets
export DEVELOPER_ID='Developer ID Application: Your Name (TEAMID)'
export NOTARY_PROFILE='<profile-name>'

Entwicklung-Installation auf dem eigenen Rechner (schnell – ohne Notarisierung)

make install-signed     # build + Developer ID sign + copy to ~/bin

Verwenden Sie dies, um eine stabile FDA-Berechtigung auf Ihrem eigenen Mac zu erhalten, ohne auf die Apple-Notarisierung warten zu müssen: Ihr eigenes Zertifikat startet lokal einwandfrei, und die Berechtigung bleibt auch bei zukünftigen Builds erhalten. Gewähren Sie ~/bin/CheAppleMailMCP einmalig vollen Datenträgerzugriff und Sie sind fertig.

Distributions-Release (signiert + notarisiert + veröffentlicht)

make release-signed VERSION=vX.Y.Z      # wraps scripts/release.sh with REQUIRE_CODESIGN=1

Damit wird eine universelle Binärdatei (arm64 + x86_64) erstellt, signiert, notarisiert (1–15 Minuten Apple-Roundtrip) und auf das GitHub-Release hochgeladen. Forks ohne Zertifikate können weiterhin ein unsigniertes Dev-Release mit SKIP_CODESIGN=1 ./scripts/release.sh vX.Y.Z bauen.

Mitwirken

Beiträge sind willkommen! Fühlen Sie sich frei, einen Pull Request zu senden.

Lizenz

MIT-Lizenz – siehe LICENSE für Details.

Autor

Erstellt von Che Cheng (@kiki830621)

Wenn Ihnen das nützlich ist, würden Sie vielleicht gerne einen Stern vergeben.