email-mcp

Kleiner persönlicher MCP-Server für ein einzelnes Postfach über IMAP + SMTP.

Er ist in erster Linie für eine private Einrichtung gedacht:

• ein Postfach

• Anmeldedaten werden über Umgebungsvariablen bereitgestellt

• E-Mails über IMAP lesen

• E-Mails über SMTP senden

• funktioniert gut mit den Standardeinstellungen von Yandex Mail, kann aber auf jeden beliebigen IMAP/SMTP-Anbieter eingestellt werden

Was ich geändert habe

Dieses Repo funktionierte ursprünglich nur im stdio-Modus. Das ist für lokale MCP-Clients in Ordnung, aber die ChatGPT-Webintegration benötigt einen HTTP-MCP-Endpunkt. Der Server unterstützt jetzt:

• stdio für die lokale Nutzung/Entwicklung

• streamable-http für die Nutzung mit der ChatGPT-Web-App

• sse für Kompatibilität

Ich habe auch ein Problem mit dem E-Mail-Threading behoben:

• der alte reply_to-Parameter setzte nur den Reply-To-Header

• echte Antworten sollten normalerweise In-Reply-To und References verwenden

• read_email gibt jetzt diese Header zurück, sodass sie an send_email zurückgegeben werden können

Außerdem habe ich die Ausgabe von read_email verbessert, indem Folgendes zurückgegeben wird:

• dekodierte Header

• Anhang-Metadaten

• Message-Threading-Header

Related MCP server: IMAP/SMTP Email MCP Server

Unterstützung für Anhänge

Diese Version unterstützt sowohl das Lesen als auch das Senden von Anhängen.

Herunterladen eines Anhangs aus einer empfangenen E-Mail

1. Rufen Sie read_email(uid=..., folder="INBOX") auf

2. Überprüfen Sie die Liste attachments

3. Verwenden Sie attachment_index mit get_attachment(...)

get_attachment(...) gibt Folgendes zurück:

• filename

• content_type

• size_bytes

• content_base64

Senden von Anhängen in ausgehenden E-Mails

send_email(...) akzeptiert eine Liste attachments.

Jedes Element kann eines der folgenden sein:

{"path": "/path/to/file.pdf"}

{"filename": "note.txt", "content_text": "hello from MCP"}

{"filename": "report.pdf", "content_base64": "JVBERi0x...", "content_type": "application/pdf"}

Verhalten des Ordners "Gesendet"

Nachdem das Senden per SMTP erfolgreich war, wird dieselbe MIME-Nachricht an Ihren IMAP-Ordner für gesendete Nachrichten angehängt.

Standardmäßig lautet dieser Ordnername:

Sent

Sie können ihn überschreiben, falls Ihr Postfach einen anderen IMAP-Ordnernamen verwendet:

export SENT_FOLDER="Sent"
# or
export MAILBOX_SENT_FOLDER="Sent"

Wenn gesendete E-Mails nicht angezeigt werden, führen Sie zuerst list_folders() aus und verwenden Sie den exakten Ordnernamen, den Ihr Postfach zurückgibt.

Dateien

• server.py — MCP-Tool-Definitionen und Transport-Start

• mail_ops.py — IMAP/SMTP-Implementierung

• requirements.txt — Python-Abhängigkeiten

Umgebung

Erforderlich:

export MAILBOX_EMAIL="you@example.com"
export MAILBOX_PASSWORD="your-app-password"

Optionale Anbietereinstellungen:

export IMAP_HOST="imap.yandex.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yandex.com"
export SMTP_PORT="465"

Optionale Einstellung für den Ordner "Gesendet":

export SENT_FOLDER="Sent"

Optionale MCP-Server-Einstellungen:

export MCP_TRANSPORT="stdio"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"

Aliase werden der Einfachheit halber ebenfalls unterstützt:

export YANDEX_EMAIL="you@yandex.ru"
export YANDEX_APP_PASSWORD="..."

Installation

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Lokal mit stdio ausführen

python server.py

Dies ist der richtige Modus für lokale MCP-Clients, die den Prozess direkt starten.

Ausführen für die ChatGPT-Web-App

Die ChatGPT-Web-App benötigt einen öffentlichen HTTPS-MCP-Endpunkt. Starten Sie den Server im HTTP-Modus:

python server.py --transport streamable-http --host 0.0.0.0 --port 8000

Stellen Sie diesen Port dann über einen öffentlichen HTTPS-Tunnel oder Reverse-Proxy bereit und registrieren Sie die resultierende MCP-URL in ChatGPT.

Verfügbare Tools

list_folders()

Listet verfügbare IMAP-Ordner auf.

search_emails(folder="INBOX", text=None, unseen_only=False, since_date=None, limit=30)

Durchsucht Nachrichten nach IMAP-Kriterien.

Gibt Elemente zurück wie:

• uid

• subject

• from

• to

• date

• flags

• size_bytes

read_email(uid, folder="INBOX")

Ruft eine vollständige Nachricht ab, ohne sie als gelesen zu markieren.

Gibt zurück:

• dekodierte Header

• message_id

• in_reply_to

• references

• attachments

• body_plain

• body_html

get_attachment(uid, folder="INBOX", attachment_index=None, filename=None)

Ruft einen einzelnen Anhang ab und gibt ihn als Base64 zurück.

send_email(...)

Sendet eine Nachricht über SMTP.

Wichtige Parameter:

• reply_to_header — setzt den Reply-To-Header

• in_reply_to — Threading-Header

• references — Threading-Header

• attachments — optionale Liste von Anhang-Spezifikationen

Für eine echte Antwort verwenden Sie in_reply_to und normalerweise auch references.

Yandex-Hinweise

Typische Yandex-Standardeinstellungen sind:

• IMAP: imap.yandex.com:993 über SSL/TLS

• SMTP: smtp.yandex.com:465 über SSL/TLS

Verwenden Sie ein App-Passwort, nicht Ihr Haupt-Kontopasswort.

Nächste sinnvolle Upgrades

• Inline-/eingebettete Bildanhänge

• Größenbeschränkungen für Anhänge und Streaming

• Tools zum Verschieben/Archivieren/Löschen mit Bestätigung

• OAuth anstelle von umgebungsbasierten Anmeldedaten

• Tests mit gemockten IMAP/SMTP-Backends