mail-mcp-oauth

Servidor MCP autoalojado de IMAP/SMTP para Claude.ai con OAuth 2.1 habilitado: un fork de maxx3250/claude-mail-mcp con una capa integrada de OAuth 2.1 + Dynamic Client Registration + PKCE, y adaptado para ejecutarse como un único proceso sin estado en Render (sin VPS, sin nginx, sin systemd, sin disco persistente).

Multicuenta: una sola implementación sirve varios buzones (Gmail, dominios personalizados, ...), cada uno accesible vía IMAP/SMTP. Cada herramienta MCP acepta un parámetro opcional account para elegir sobre qué buzón actuar.

Qué cambia con respecto al upstream

• OAuth 2.1 integrado (src/oauth.ts): /register (DCR), /authorize (PKCE + formulario de inicio de sesión de un solo usuario), /token. No hay un proceso de shim de OAuth separado: el upstream menciona uno, pero no está publicado, así que este fork lo implementa directamente en la misma aplicación Express.

• Sin estado por diseño: los tokens de acceso y de actualización son JWT firmados (sin base de datos); los clientes OAuth registrados y los códigos de autorización en curso están en memoria (un reinicio solo hace que Claude.ai se re-registre silenciosamente, algo que su cliente MCP ya controla).

• Cuentas desde una variable de entorno: ACCOUNTS_JSON en lugar de un archivo en disco, porque el sistema de archivos de Render es efímero. El archivo ACCOUNTS_FILE sigue funcionando para uso local/VPS.

• Se eliminaron las herramientas de CalDAV/calendario: no son necesarias para este despliegue y reducen la superficie de dependencias (tsdav, ical.js).

Related MCP server: IMAP MCP Server

Arquitectura

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

Configuración local

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

Despliegue en Render

Consulta docs/DEPLOY_RENDER.md para el paso a paso completo (push a GitHub, servicio web Render, dominio personalizado, DNS de Netcup, conexión con Claude.ai).

Cuentas

Consulta docs/ACCOUNTS.md para el esquema de accounts.json y la configuración por proveedor (contraseñas de aplicación de Gmail, Netcup Webhosting IMAP/SMTP, y por qué Hotmail/Outlook.com necesita un flujo OAuth2 separado).

Herramientas expuestas a Claude

Licencia

MIT — consulta LICENSE. Obra original de Markus Stöger (maxx3250/claude-mail-mcp).