mail-mcp-oauth

Self-hosted, OAuth 2.1-enabled IMAP/SMTP MCP server for Claude.ai — a fork of maxx3250/claude-mail-mcp with a built-in OAuth 2.1 + Dynamic Client Registration + PKCE layer, and adapted to run as a single stateless process on Render (no VPS, no nginx, no systemd, no persistent disk).

Multi-account: one deployment serves several mailboxes (Gmail, custom domains, ...), each accessible via IMAP/SMTP. Every MCP tool takes an optional account parameter to pick which mailbox to act on.

What changed vs. upstream

• OAuth 2.1 built in (src/oauth.ts): /register (DCR), /authorize (PKCE + single-user login form), /token. No separate OAuth shim process — upstream references one but it isn't published, so this fork implements it directly in the same Express app.

• Stateless by design: access/refresh tokens are signed JWTs (no DB). DCR client registrations are also signed JWTs (the client_id carries its own registration), so a restart needs no re-registration. In-flight auth codes are the only in-memory state, and they live 2 minutes.

• Persistent login: a successful /authorize sets a signed, 10-year mcp_session cookie, so later re-authorizations (Claude.ai re-checks periodically; Render free cold-starts trigger one) complete silently with no login prompt. Revoke by rotating JWT_SECRET. See docs/DEPLOY_RENDER.md.

• Accounts from an env var: ACCOUNTS_JSON instead of a file on disk, since Render's filesystem is ephemeral. File-based ACCOUNTS_FILE still works for local/VPS use.

• CalDAV/calendar tools removed — not needed for this deployment, cuts the dependency surface (tsdav, ical.js).

• Sending via HTTP APIs, not direct SMTP: Render's free tier blocks all outbound traffic to SMTP ports (25/465/587) — confirmed against four different mailboxes across three providers, not fixable from our side. send_message picks, per account: the Gmail API (src/gmail-client.ts) for any Google-hosted address (the only way to authenticate as a domain you don't control DNS for), else Brevo's HTTP API (src/brevo-client.ts) if BREVO_API_KEY is set, else direct SMTP. IMAP is unaffected regardless. See docs/ACCOUNTS.md.

• Google OAuth2 (src/google-oauth.ts): XOAUTH2 for IMAP + Gmail API for sending, for Gmail personal and Google Workspace mailboxes (the latter needs it for IMAP too — app passwords disabled by admin policy, no password path exists at all).

Related MCP server: Gmail MCP Server

Architecture

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) per account, XOAUTH2 or password
    │     └── send_message ──▶ Gmail API (Google accounts) or Brevo HTTPS API (SMTP ports blocked on Render free tier)
    └── /health

Local setup

npm install
cp .env.example .env
# fill in PUBLIC_URL, ACCOUNTS_JSON (see docs/ACCOUNTS.md), OAUTH_USER,
# OAUTH_PASS, JWT_SECRET (openssl rand -hex 32), and BREVO_API_KEY
# (only needed if raw SMTP egress is blocked where you're deploying)
npm run dev

Deploying to Render

See docs/DEPLOY_RENDER.md for the full step-by-step (GitHub push, Render web service, custom domain, Netcup DNS, connecting Claude.ai).

Accounts

See docs/ACCOUNTS.md for the accounts.json schema, per-provider setup (Gmail app passwords, Netcup Webhosting IMAP/SMTP, Google OAuth2 for Gmail + Workspace), the Brevo sender-domain- authentication steps for non-Google domains, and why Hotmail is currently blocked on a Microsoft-side issue rather than anything in this repo.

Tools exposed to Claude

License

MIT — see LICENSE. Original work by Markus Stöger (maxx3250/claude-mail-mcp).