imap-mcp

Verbinde jedes Postfach mit deinem zweiten Gehirn.

Ein MCP-Server, der E-Mails über IMAP liest — iCloud, Gmail, Outlook, Fastmail, Uni- oder Firmenpost, alles, was das Protokoll spricht — und sie in durchsuchbare Markdown-Notizen verwandelt, plus RawItem-Datensätze, die die Mycelium-Laufzeit direkt aufnimmt.

MIT-lizenziert. Läuft auf macOS, Linux und Windows.

Warum IMAP

Jeder E-Mail-Anbieter spricht IMAP. Ein Connector deckt alle ab, was entscheidend ist, wenn in einem Raum voller Leute jeder ein anderes Postfach mitbringt.

Wo ein Anbieter bereits einen ordentlichen OAuth-Connector hat, bevorzuge ihn — google-workspace-mcp für Gmail, microsoft-365-mcp für Outlook. OAuth bietet eingeschränkten, widerrufbaren Zugriff; ein IMAP-App-Passwort nicht. Dieser Server ist für die Postfächer, die diese beiden nicht erreichen können: iCloud, das für Mail überhaupt kein OAuth-Grant veröffentlicht, und alle kleineren oder selbst gehosteten Anbieter.

Related MCP server: imap-2-mcp

Unterstützte Anbieter

Frag den Server selbst mit imap_list_providers — er liefert den Host jedes Anbieters und die genaue Seite, auf der du ein Passwort erstellst.

Einrichtung

Siehe SETUP.md. Drei Schritte, und du erstellst das Passwort selbst.

Tools

Acht Aktionen, unter der ~15er-Schwelle, ab der eine Such-+Ausführungs-Oberfläche sich zu lohnen beginnt, also ein Tool pro Aktion.

Sicherheit

Dein Postfach wird nie verändert. Sitzungen öffnen mit EXAMINE (schreibgeschützt) und jeder Abruf verwendet BODY.PEEK[]. Ein einfaches FETCH BODY[] setzt das \Seen-Flag als Nebeneffekt, sodass eine "schreibgeschützte" Synchronisierung deine ungelesenen E-Mails stillschweigend als gelesen markieren würde. Das einzige Tool, das etwas schreibt, schreibt Notizen in dein Vault.

Dein Passwort verlässt nie deinen Rechner. Es liegt im OS-Keychain, wird nie in eine Konfigurationsdatei geschrieben, nie protokolliert und nie von einem Tool zurückgegeben. IMAP-LOGIN-Fehler geben den fehlgeschlagenen Befehl zurück — der das Passwort enthält —, daher werden Authentifizierungsfehler komplett ersetzt statt durchgereicht.

E-Mail wird als unvertrauenswürdige Eingabe behandelt. Jeder Nachrichtentext wird in einen UNTRUSTED_EMAIL_BODY-Rahmen gewickelt, und ein Text, der das schließende Markierungszeichen fälscht, um aus seinem eigenen Rahmen auszubrechen, wird neutralisiert. E-Mail sind Daten zum Zusammenfassen, nie Anweisungen zum Befolgen. Das ist wichtiger, als es klingt: Jeder kann dir eine E-Mail schicken, also ist ein ungerahmter Text ein Fremder, der direkt in den Kontext deines Assistenten schreibt.

Nichts wird stillschweigend übersprungen. Wenn der Server ein Postfach neu nummeriert (UIDVALIDITY geändert), wird der Synchronisations-Cursor verworfen und die Antwort sagt uidvalidity_reset: true — ein veralteter Cursor würde sonst auf unzusammenhängende Nachrichten zeigen und echte E-Mails für immer überspringen. Gefilterte Nachrichten tragen die Regel, die sie aussortiert hat, und imap_explain_filter erklärt jede einzelne.

Jeder Schreibvorgang sagt, wohin er ging. Ergebnisse tragen vault_root und root_source, sodass E-Mails, die im falschen Ordner landen, in der ersten Antwort sichtbar sind, statt Monate später entdeckt zu werden.

Filter

Intelligente Standardeinstellungen behalten, was wichtig ist, und verwerfen das Rauschen. Ordnernamen unterscheiden sich je nach Anbieter und Sprache, also kommen sie aus dem Anbieterprofil statt hartcodiert zu sein — Gmail verschachtelt unter [Gmail]/, Outlook sagt Junk Email, ein Konto mit spanischer Locale sagt Enviados.

Expliziter Block schlägt explizite Freigabe; beide schlagen intelligente Standardeinstellungen. Schalte die Standardeinstellungen komplett ab mit apply_smart_filter=False.

Zwei Konsumenten, ein Kern

imap_client.py ist das einzige Modul, das IMAP spricht.

• Zweites Gehirn — imap_sync_to_vault schreibt External Inputs/<Provider>/<mailbox>/YYYY-MM-DD-<slug>.md

• Mycelium-Laufzeit — imap_export_for_runtime erzeugt Datensätze, die dem RawItem der Laufzeit Feld für Feld entsprechen, sodass der serverseitige Adapter dies umschließt, statt es neu zu implementieren

Tests

uv run pytest -q

65 Tests, kein Netzwerk erforderlich. Die Sicherheitswächter (Fence-Escape, Pfad-Eindämmung, Nicht-Leckage von Anmeldedaten) wurden jeweils mutation-getestet: Wächter entfernt, der zugehörige Test als fehlschlagend bestätigt, Wächter wiederhergestellt.

Noch nicht verifiziert: Es wurde kein Live-Smoke-Test gegen ein echtes Postfach bei einem Anbieter ausgeführt. Jeder Test verwendet synthetische Testdaten, was die Parsing- und Filterlogik beweist, aber nicht, dass ein Live-Server diese exakten Befehle akzeptiert.