Proton Mail MCP Server

Proton Suite Agent

MCP server multi-producto para Proton Suite: Mail (Bridge IMAP/SMTP), Pass (pass-cli), Drive (CLI oficial) y Calendar (CalDAV stub). Un agente puede operar el buzón, gestionar contraseñas, sincronizar archivos y clasificar correo — todo sin salir de tu máquina.

---

Quickstart

Prerrequisitos: Node ≥ 22, Proton Mail Bridge corriendo en local, pass + gpg para contraseñas.

1. Instalar y compilar

git clone https://github.com/Iniciativas-Alexendros/agent-protonsuite.git
cd agent-protonsuite
npm install && npm run build && npm run smoke

2. Configurar variables de entorno

export PROTON_BRIDGE_USER=you@proton.me
export PROTON_BRIDGE_PASS=your-bridge-password
export PROTON_MAIL_FROM=you@proton.me

3. Conectar tu cliente MCP

{
  "mcpServers": {
    "protonsuite": {
      "command": "npx",
      "args": ["-y", "@alexendros/protonsuite-agent", "protonsuite-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PROTON_BRIDGE_USER": "you@proton.me",
        "PROTON_BRIDGE_PASS": "your-bridge-password",
        "PROTON_MAIL_FROM": "you@proton.me",
        "PROTON_BRIDGE_TLS_INSECURE": "true",
        "PROTON_PASS_ENABLED": "true",
      },
    },
  },
}

Seguridad: usa PROTON_PASS_BRIDGE_PATH=proton/bridge/password o el wrapper JIT en connectors/stdio-wrapper.sh.example para no dejar el bridge password en disco.

4. Organizar el buzón (dry-run)

AGENT_DRY_RUN=true npx -y @alexendros/protonsuite-agent organize

El agente analiza el inbox y presenta un plan de carpetas, etiquetas y alertas sin aplicar cambios. Desactiva AGENT_DRY_RUN para ejecutar.

---

Tools MCP

25 tools organizadas por producto. Todas aceptan response_format: "markdown" | "json".

Ver tabla completa en docs/agent-quickstart.md.

---

Agente

Drive CLI

# Instalar (opcional)
sudo wget -q 'https://proton.me/download/drive/cli/linux/proton-drive' \
  -O /usr/local/bin/proton-drive && sudo chmod +x /usr/local/bin/proton-drive
proton-drive auth login

Requiere DRIVE_ENABLED=true (default). Ver docs/drive-audit.md para configuración completa.

---

Despliegue

Docker

docker compose up -d

Ver docs/deployment-http-docker.md para auth, allowlist y healthcheck.

Instalador Ubuntu

bash scripts/install.sh

Ver scripts/install.sh para la instalación interactiva completa.

---

Documentación

Conectores

Playbooks

playbooks/ — workflows predefinidos: onboarding, organize inbox, triage, fraud detection, pass audit, daily briefing, setup checklist.

---

Calidad

npm run typecheck   # TypeScript strict
npm test            # 745 tests (Vitest)
npm run coverage    # Coverage (v8 — 98.05% statements)
npm run build       # Compilación
npm run smoke       # Verificación stdio
npm run knip        # Unused deps/exports

Seguridad

• Bearer timing-safe, origin allowlist, rate-limit 120/min/token.
• Per-session HTTP transport, sesiones idle evicted a los 30 min.
• Sin credenciales ni cuerpos de request en logs.
• Pass nunca expone valores de secreto — solo {found: true}.
• Dry-run por defecto en el agente.

---

Próximo módulo objetivo (branches <95%) — agrupado por dominio:

• Agent: agent/organizer.ts (74.20%), agent/executor.ts (87.20%)
• MCP surface: server/drive.ts (88.00%), server/mail.ts (89.60%)
• Ecosystem: ecosystem/discovery.ts (86.80%)

Progreso de cobertura

Conteo de tests canónico: npx vitest run 2>&1 | grep -E 'Test Files|Tests'. Los modos vitest run --coverage y vitest list pueden diferir ligeramente por su modelo de carga (transform/collect timing).

Licencia

AGPL-3.0 — Copyright 2026 Alejandro Domingo Agustí (Alexendros). Sin afiliación a Proton AG.

Ver NOTICE.md para dependencias y compatibilidad de licencias.