mail-mcp

Selbst gehosteter, anbieterunabhängiger Mail-Dienst. Richten Sie ihn auf die IMAP/SMTP-Anmeldedaten eines beliebigen Postfachs aus und er bietet:

• REST-API – spiegelt die gängigen Postfachoperationen wider: Ordner auflisten, Nachrichten auflisten/abrufen/suchen, senden, markieren, verschieben, löschen, Kontingent (nach bestem Wissen).

• Webhooks (message.received) über einen persistenten IMAP-IDLE-Beobachter – sendet einen HTTP-POST (mit einem pro Webhook festgelegten Bearer-Secret) bei jedem neuen E-Mail-Eingang, wiederholt mit exponentiellem Backoff (bis zu 6 Versuche), falls der empfangende Endpunkt fehlschlägt.

• MCP-Server (Streamable HTTP, POST /mcp) – stellt dieselben Operationen als Werkzeuge bereit, sodass jeder MCP-kompatible Agent sie direkt nutzen kann.

Von Anfang an mit mehreren Postfächern: Fügen Sie beliebig viele Konten zu config/accounts.json hinzu.

Anfragekörper der REST-API werden mit Zod validiert (lib/schemas.js) – ungültige Nutzdaten erhalten einen 422 ERR_VALIDATION_FAILED mit Fehlern auf Feldebene, bevor sie die Mail-Ebene erreichen. Webhook-Abonnements werden in SQLite gespeichert (config/webhooks.sqlite, über better-sqlite3) anstatt in einer flachen JSON-Datei. Nachrichten, die größer als MAIL_MCP_MAX_MESSAGE_SIZE (Standard 25 MB) sind, werden mit bodyTruncated: true und ohne geparsten Body/Anhänge zurückgegeben, um zu vermeiden, dass große Nachrichten in den Speicher geladen werden.

Einrichtung

npm install
cp .env.example .env   # fill in MAIL_MCP_API_TOKEN and one MAILMCP_PASS_<ID> per account

Kopieren Sie config/accounts.json.example nach config/accounts.json (in .gitignore – auch in dieser Datei keine Passwörter, diese befinden sich nur in .env):

[
  {
    "id": "example",
    "user": "user@example.com",
    "imap": { "host": "imap.example.com", "port": 993, "secure": true },
    "smtp": { "host": "smtp.example.com", "port": 465, "secure": true }
  }
]

Das Passwort für das Konto id: "example" wird aus MAILMCP_PASS_EXAMPLE gelesen.

node index.js

Läuft standardmäßig auf 127.0.0.1:4900 (siehe MAIL_MCP_PORT). Stellen Sie es hinter einen Reverse-Proxy mit TLS, wenn Sie es von außerhalb des Hosts erreichen möchten.

Related MCP server: Agent Email

systemd

Eine Beispiel-Unit befindet sich in deploy/mail-mcp.service – kopieren Sie sie nach /etc/systemd/system/, passen Sie die Pfade an, und sie lädt Geheimnisse aus /root/mail-mcp/.env über EnvironmentFile.

Authentifizierung

Jede REST- und MCP-Anfrage erfordert Authorization: Bearer <MAIL_MCP_API_TOKEN>.

Tests

npm test              # run once
npm run test:coverage # run with coverage report

Die Abdeckung umfasst die reinen/Logik-Module (lib/schemas.js, lib/accounts.js, lib/webhooks-store.js). lib/mailclient.js und lib/idle-watcher.js kommunizieren mit echten IMAP/SMTP-Servern und werden stattdessen durch manuelles End-to-End-Testen überprüft – sie sind vom Abdeckungs-Badge ausgeschlossen, damit dieser nicht irreführend ist.