mail-mcp-oauth

Selbstgehosteter, OAuth-2.1-fähiger IMAP/SMTP-MCP-Server für Claude.ai – ein Fork von maxx3250/claude-mail-mcp mit einer eingebauten Schicht für OAuth 2.1, Dynamic Client Registration und PKCE, angepasst für den Betrieb als einzelner zustandsloser Prozess auf Render (ohne VPS, ohne nginx, ohne systemd, ohne dauerhaften Datenträger).

Multi-Konto: Eine einzige Bereitstellung kann mehrere Postfächer bedienen (Gmail, eigene Domains, ...), jeweils erreichbar über IMAP/SMTP. Jedes MCP-Tool akzeptiert einen optionalen Parameter account, um festzulegen, auf welches Postfach zugegriffen wird.

Änderungen gegenüber dem Upstream

• OAuth 2.1 eingebaut (src/oauth.ts): /register (DCR), /authorize (PKCE + Login-Formular für Einzelnutzer), /token. Kein separater OAuth-Shim-Prozess mehr – das Upstream-Projekt erwähnt zwar einen, hat ihn aber nicht veröffentlicht. Dieser Fork setzt OAuth daher direkt in derselben Express-App um.

• Bewusst zustandslos: Access- und Refresh-Tokens sind signierte JWTs (ohne Datenbank); registrierte OAuth-Clients und labstende Autorisierungscodes werden im Speicher vorgehalten. Ein Neustart führt ledlich dazu, dass Claude.ai stillschweigend erneut registriert wird – was sein MCP-Client bereits abdeckt.

• Konten über eine Umgebungsvariable: ACCOUNTS_JSON statt einer Datei auf der Platte, da das Dateisystem von Render nicht dauerhaft ist. Die dateibasierte ACCOUNTS_FILE funktioniert weiterhin für den lokalen/VPS-Einsatz.

• CalDAV-/Kalender-Tools entfernt – für dieses Deployment nicht nötig, reduziert die Abhängigkeiten (tsdav, ical.js).

Related MCP server: IMAP MCP Server

Architektur

Claude.ai (web)
    │  HTTPS + OAuth 2.1 (DCR, PKCE, JWT)
    ▼
Render (TLS terminated automatically, custom domain mcp-mail.<domain>)
    ▼
this process (single Node service)
    ├── /.well-known/oauth-authorization-server, /register, /authorize, /token   (src/oauth.ts)
    ├── /mcp  (Bearer-gated MCP Streamable HTTP transport)
    │     ├── ImapClient   ──▶ imapflow   ──▶ IMAP server (993/143) per account
    │     └── SmtpClient   ──▶ nodemailer ──▶ SMTP server (465/587) per account
    └── /health

Lokale Einrichtung

npm install
cp .env.example .env
# fill in PUBLIC_URL, ACCOUNTS_JSON (see docs/ACCOUNTS.md), OAUTH_USER,
# OAUTH_PASS, and JWT_SECRET (openssl rand -hex 32)
npm run dev

Bereitstellung auf Render

Siehe docs/DEPLOY_RENDER.md für die vollständige Schritt-für-Schritt-Anleitung (GitHub-Push, Render-Webservice, eigene Domain, Netcup-DNS, Verbindung von Claude.ai).

Konten

Siehe docs/ACCOUNTS.md für das accounts.json-Schema und die Einrichtung der jeweiligen Anbieter (App-Passwörter bei Gmail, Netcup Webhosting IMAP/SMTP und warum Hotmail/Outlook.com einen separaten OAuth2-Flow benötigt).

Claude verfügbare Tools

License

MIT – siehe LICENSE. Original von Markus Wanner (masonr25/claude-mail-mcp).