Proton Mail MCP

Servidor MCP (Model Context Protocol) para Proton Mail vía Proton Mail Bridge. Expone la bandeja — lectura, búsqueda, envío, mover, etiquetar, borrar — a cualquier cliente MCP con tipado estricto, anotaciones de seguridad y doble transporte (stdio y streamable HTTP).

La garantía E2E de Proton se preserva: el cifrado y descifrado ocurren en Bridge, una máquina que controlas tú. Ni los servidores de Anthropic ni terceros ven tu correo descifrado — sólo el agente al que tú autorizas.

Por qué existe este proyecto

Hay dos formas comunes de darle "ojos sobre el correo" a un asistente como Claude:

1. Copiar y pegar bloques de correo dentro del chat. Trabajoso, frágil y sin trazabilidad.
2. OAuth contra un proveedor SaaS (Gmail API, Microsoft Graph). Funciona pero expone los datos al proveedor y deja el agente fuera de una cuenta Proton Mail, que es E2E y no tiene API pública.

Este MCP resuelve ambos problemas sobre Proton Mail:

• Interfaz MCP estándar. Cualquier cliente compatible (Claude Code CLI, Claude Routines, SDK cliente en tu backend) puede llamar a las 13 tools sin implementar IMAP/SMTP.
• Autohospedado. El binario corre donde tú decidas — laptop, VPS, contenedor. Bridge hace la criptografía en el mismo host y nunca expone el vault a la red pública.
• Dual transport. stdio para cliente local (Claude Code en la CLI), streamable HTTP con bearer auth + allowlist de origen para clientes remotos (Routines, dashboards propios).

Este repositorio también sirve como muestra pública de craft: tests automatizados, hardening por capas, CI/CD completo y modelo de amenazas explícito — no es un boilerplate, es una pieza de producción.

Estado actual

Arquitectura

┌─────────────────────────────────────────────────────────────────────────┐
│                            CONSUMIDORES MCP                             │
│                                                                         │
│   Claude Code CLI          Claude Routines         Backend propio       │
│   (stdio, local)           (HTTP, claude.ai)       (HTTP, tu código)    │
│         │                         │                       │             │
└─────────┼─────────────────────────┼───────────────────────┼─────────────┘
          │ JSON-RPC                │ HTTPS + Bearer        │ HTTPS + Bearer
          │                         │ + Origin allowlist    │
          ▼                         ▼                       ▼
    ┌──────────────────────────────────────────────────────────────┐
    │                      proton-mail-mcp                         │
    │     TypeScript · @modelcontextprotocol/sdk@^1.19             │
    │     Dual transport · Per-session StreamableHTTP              │
    │     Bearer timing-safe · Rate-limit 120/min/token            │
    │                                                              │
    │   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌─────────┐   │
    │   │config.ts │   │ auth.ts  │   │  http.ts │   │server.ts│   │
    │   │Zod env   │   │bearer    │   │Express + │   │ 13 MCP  │   │
    │   │validation│   │timing-   │   │per-sess. │   │ tools + │   │
    │   │stderr log│   │safe cmp  │   │transport │   │ Zod in  │   │
    │   └──────────┘   └──────────┘   └──────────┘   └────┬────┘   │
    │                                                     │        │
    │              ┌───────────────────┐   ┌──────────────┴──────┐ │
    │              │      imap.ts      │   │       smtp.ts       │ │
    │              │   imapflow pool   │   │   nodemailer pool   │ │
    │              │   retry+backoff   │   │   threading headers │ │
    │              │   mailbox locks   │   │   quote/forward     │ │
    │              └─────────┬─────────┘   └──────────┬──────────┘ │
    └────────────────────────┼────────────────────────┼────────────┘
                             │ IMAP 1143              │ SMTP 1025
                             │ STARTTLS               │ STARTTLS
                             ▼                        ▼
                    ┌────────────────────────────────────────┐
                    │         Proton Mail Bridge             │
                    │     (localhost o VPS interno)          │
                    │       FRONTERA CRIPTOGRÁFICA E2E       │
                    └────────────────┬───────────────────────┘
                                     │ OpenPGP + HTTPS
                                     ▼
                            ┌──────────────────┐
                            │ Proton Servers   │
                            │ (cifrado E2E)    │
                            └──────────────────┘

Claves de diseño:

• Fontera cripto: todo lo que está a la izquierda de Bridge opera sobre correo en claro. Bridge vive en una máquina que tú controlas, en una red que tú controlas. Nada se filtra a terceros.
• Per-session HTTP transport: un StreamableHTTPServerTransport por Mcp-Session-Id (recomendación del SDK). Evita bleed de estado entre clientes concurrentes (Routines + Command Center + CLI pueden convivir).
• Pool persistente IMAP/SMTP: se reutiliza una conexión a Bridge entre llamadas. Reconexión con retry + backoff exponencial si Bridge se reinicia.
• Stderr-only logs: en modo stdio, stdout está reservado a JSON-RPC. Contaminarlo rompería el protocolo.

Las 13 tools

Todas las tools de lectura aceptan response_format: "markdown" | "json".

Cada tool se registra con annotations del SDK — readOnlyHint, idempotentHint, destructiveHint, openWorldHint — para que el modelo pueda razonar sobre el efecto antes de invocarla.

Tres caminos de integración

1 · Claude Code CLI (local, stdio)

Ideal para el día a día en el workstation. Bridge corre en la máquina; el MCP se lanza vía stdio cuando Claude Code lo necesita.

claude mcp add --transport stdio proton-mail --scope user \
  --env PROTON_BRIDGE_USER=tu@proton.me \
  --env PROTON_BRIDGE_PASS=tu-bridge-password \
  --env PROTON_MAIL_FROM=tu@proton.me \
  --env PROTON_BRIDGE_TLS_INSECURE=true \
  --env MCP_TRANSPORT=stdio \
  -- node /ruta/absoluta/a/proton-mail-mcp/dist/index.js

Dentro de cualquier sesión de Claude Code, el comando /mcp muestra proton-mail: connected y las 13 tools. A partir de ahí, lenguaje natural: "resume mis correos no leídos de la última semana por tema".

2 · Claude Routines (claude.ai, HTTP)

Routines necesita un endpoint HTTPS público. Tras desplegar en Dokploy (abajo), se añade como Remote MCP Server:

• URL: https://tu-dominio.com/mcp
• Authorization: Bearer <MCP_AUTH_TOKEN>

Y se programan rutinas declarativas:

"Cada lunes a las 9:00, busca en INBOX correos no leídos de los últimos 7 días, clasifícalos por tema (software / administraciones / finanzas / personal / legal), y envíame un resumen markdown a mi propia cuenta."

3 · Backend propio (HTTP, SDK oficial o fetch)

El servidor habla JSON-RPC estándar. El ejemplo oficial usa @modelcontextprotocol/sdk:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL(process.env.PROTON_MCP_URL!),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.PROTON_MCP_TOKEN!}` } } },
);
const client = new Client({ name: "mi-backend", version: "1.0.0" });
await client.connect(transport);

const { content } = await client.callTool({
  name: "proton_search_emails",
  arguments: { query: "factura", unseen_only: true, limit: 10 },
});

Para ahorrarte esa dependencia, este repo incluye también un cliente fetch de ~130 líneas en extras/ (ver Integración en Next.js).

Quickstart local

Prerrequisitos: Node ≥ 20, Proton Mail Bridge corriendo en el workstation (GUI o distrobox), y el bridge password a mano (no es tu password Proton — lo muestra Bridge en Account → Mailbox password).

git clone https://github.com/Alexendros/proton-mail-mcp.git
cd proton-mail-mcp
npm install
npm run build
npm test        # 39 tests verdes
npm run smoke   # verifica stdio: initialize + tools/list

Crea .env desde el template:

cp .env.example .env
# edita PROTON_BRIDGE_USER, PROTON_BRIDGE_PASS y PROTON_MAIL_FROM

Arranca en modo stdio contra Bridge local:

PROTON_BRIDGE_USER=tu@proton.me \
PROTON_BRIDGE_PASS=xxx \
PROTON_MAIL_FROM=tu@proton.me \
PROTON_BRIDGE_TLS_INSECURE=true \
MCP_TRANSPORT=stdio \
node dist/index.js

O con el inspector oficial (UI gráfica para probar tools):

npm run inspect
# → abre http://localhost:6274

Producción: Docker + Dokploy

El repo incluye todo para un despliegue autohospedado con dos contenedores: bridge (Proton Mail Bridge headless) y mcp (este servidor en HTTP). Traefik emite un cert Let's Encrypt automáticamente.

1. Variables en Dokploy

PROTON_BRIDGE_USER=tu@proton.me
PROTON_BRIDGE_PASS=<se rellena tras login inicial>
PROTON_MAIL_FROM=tu@proton.me
MCP_AUTH_TOKEN=<openssl rand -hex 32>
MCP_ALLOWED_ORIGINS=https://claude.ai,https://tu-dashboard.com
LOG_LEVEL=info

Todas las variables se validan en arranque con Zod. En NODE_ENV=production, el servidor se niega a arrancar si MCP_ALLOWED_ORIGINS está vacío (evita exposición accidental a cualquier origen).

2. Login one-off al Bridge headless

La primera vez hay que iniciar sesión interactivamente en Bridge (TTY):

ssh tu-vps
docker run --rm -it \
  -v <volumen-bridge-data>:/root \
  --entrypoint /bin/bash proton-mail-mcp-bridge:latest \
  -c "/protonmail/proton-bridge --cli"
# dentro:
>>> login      # username/pass/2FA
>>> info       # anota el bridge password mostrado
>>> exit

Pega ese bridge password en PROTON_BRIDGE_PASS y redeploy. El volumen persiste el vault: siguientes arranques son automáticos.

3. Verificación

curl https://tu-dominio.com/healthz
# {"ok":true,"version":"0.1.0","sessions":0}

curl -X POST https://tu-dominio.com/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

4. Registrar en Claude Code remoto

claude mcp add --transport http proton-mail-remote --scope user \
  https://tu-dominio.com/mcp \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>"

Seguridad

La hoja completa está en SECURITY.md. Resumen de los controles activos:

• Bearer timing-safe (src/auth.ts): comparación byte-a-byte en tiempo constante, con early-return por longitud para no filtrar el tamaño del token esperado.
• Origin allowlist (MCP_ALLOWED_ORIGINS): cada request /mcp se valida contra la lista exacta. Mitigación de DNS rebinding.
• Rate limit 120 req/min por token (express-rate-limit, draft-7 headers).
• Per-session transport: un StreamableHTTPServerTransport por Mcp-Session-Id, eviction tras 30 min idle.
• Attachment cap: max_bytes default 10 MB (hard cap 50 MB), con truncated=true explícito cuando aplica. Evita que un adjunto hostil sature el contexto del LLM.
• Stderr-only logging: ningún cuerpo de request, ninguna credencial en logs.
• Secrets fuera de git: .env.example muestra la forma; los valores viven en Dokploy secrets / .env local con permisos 0600.

Amenazas modeladas (T1–T7 en SECURITY.md): robo de bearer, DNS rebinding, SMTP relay abuse, prompt injection vía cuerpo de email, robo de credenciales IMAP, exfiltración vía adjuntos, downgrade TLS del canal Bridge local.

Integración en Next.js

Si tu dashboard es un Next.js (por ejemplo, el Developer Command Center que hospeda las acciones reales), el patrón que uso es un cliente fetch minimalista — evita arrastrar el SDK MCP entero cuando sólo necesitas un par de llamadas:

// src/lib/mcp/proton.ts (extracto)
export async function fetchUnreadSummary(opts: { limit?: number } = {}) {
  const mcp = await connectProtonMcp();   // initialize + session id
  try {
    const call = await mcp.callTool("proton_search_emails", {
      mailbox: "INBOX",
      unseen_only: true,
      limit: opts.limit ?? 10,
      response_format: "json",
    });
    return JSON.parse(call.content[0].text);
  } finally {
    await mcp.close();
  }
}

Y una acción sobre el patrón actions dispatcher (Zod + auth + audit log append-only):

// src/lib/actions/handlers.ts
export async function mailUnreadSummary(p: { mailbox?: string; limit?: number }) {
  const summary = await fetchUnreadSummary({ limit: p.limit });
  return { providerRef: `mailbox:${summary.mailbox}`, result: summary };
}

Desde la UI, un <ActionButton action="mail/unread-summary" /> dispara la llamada, pinta un toast, y deja rastro en el timeline append-only de /acciones.

Calidad de código

npm run typecheck    # tsc --noEmit, strict mode
npm test             # vitest run, 39 tests en 4 suites
npm run smoke        # initialize + tools/list stdio

Lo que hay tests para:

• auth.test.ts — compareTokens timing-safe en casos extremos (longitudes distintas, tokens vacíos, tokens hex de 64 chars).
• config.test.ts — Zod rechaza env missing, acepta defaults correctos, parsea CSV en allowedOrigins.
• smtp-helpers.test.ts — prefixSubject no duplica "Re:", addrMatches es case-insensitive, collectReferences preserva orden de threading.
• http-transport.test.ts — GET /healthz 200 sin auth, POST /mcp sin bearer 401, Origin inválido 403, initialize devuelve Mcp-Session-Id, rate limit middleware wired.

CI pipeline:

1. verify (matrix Node 20/22): install + typecheck + test + build + smoke
2. audit: npm audit --audit-level=high
3. docker-build: construye la imagen sin push (smoke)
4. codeql: análisis SAST JavaScript/TypeScript en push a main y semanal
5. release (en push a main): docker build + push a ghcr.io/alexendros/proton-mail-mcp:{sha,latest}

Casos de uso reales

Coste marginal de cada flujo nuevo una vez desplegado: cero.

Stack técnico

Desarrollo

src/
├── index.ts      Arranque: stdio o HTTP, signal handlers, guardrails de producción
├── config.ts     Zod env validation + logger stderr
├── auth.ts       compareTokens timing-safe + extractBearer
├── http.ts       buildHttpApp: per-session StreamableHTTP + rate-limit + origin allowlist
├── imap.ts       ImapClient: pool + retry/backoff + mailbox locks
├── smtp.ts       SmtpClient: nodemailer pool + helpers de threading (reply/forward)
└── server.ts     McpServer con registro de las 13 tools (Zod in, markdown/json out)

tests/
├── auth.test.ts
├── config.test.ts
├── smtp-helpers.test.ts
└── http-transport.test.ts

scripts/
└── smoke.sh      initialize + tools/list sobre stdio, integrable en CI

.github/workflows/
├── ci.yml        lint/typecheck/test/build/smoke + npm audit + docker build
├── release.yml   push a ghcr.io en main y tags semver
└── codeql.yml    SAST JavaScript/TypeScript

Dockerfile          imagen mcp: multi-stage node:20-alpine
Dockerfile.bridge   imagen bridge: extiende shenxn/protonmail-bridge:build con libfido2,
                    dbus-x11, credential-helpers, libGL/libOpenGL y libs Qt XCB
docker-compose.yml  stack bridge + mcp con red proton-net interna +
                    dokploy-network externa para Traefik

Roadmap abierto

• Tests E2E con Bridge de prueba (Greenmail + SMTP mock).
• outputSchema con structuredContent en las tools de lectura cuando el SDK lo materialice mejor.
• proton_watch_inbox con IDLE + webhook (flujos event-driven sin polling).
• Soporte multi-alias (Proton permite varias direcciones por cuenta).
• Bridge CA pinning opcional (PROTON_BRIDGE_CA_PATH) para cerrar tlsInsecure en producción estricta.

Sobre este proyecto

Soy Alexendros (Alejandro Domingo Agustí). Construyo productos SaaS con integración IA — este repositorio es una muestra del nivel de cuidado que aplico a cualquier pieza de infra que toco: tests antes de shippear, hardening antes de abrir puertos, docs antes de olvidar decisiones.

Si necesitas algo parecido para tu caso, cuéntamelo: contacto [at] alexendros [dot] me.

Licencia

MIT — úsalo, fórkalo, véndelo. Sin garantía.