Proton Mail Mcp

io.github.AlexendrosPublished by GitHub account Alexendrosv0.1.2Updated Oct 24, 2026

Proton Mail MCP via Bridge (IMAP/SMTP) · 13 tools · dual transport stdio + HTTP.

VerifiedSTDIODesktop onlyFiles & StorageCommunication & CollaborationSecurity & Monitoring

Overview

AI-generated overview

Local MCP server that lets an assistant operate a Proton Mail mailbox through Proton Mail Bridge over IMAP/SMTP, plus Pass and Drive tools.

What you can do
  • List, search, read, send, reply, forward, flag, move and delete mail, and handle attachments
  • List, get (without values), generate and health-check Pass entries, and audit password strength
  • Check Drive status, list, download, upload, share, audit and organize files
  • Report unified suite, Bridge, binary and agent-plan status, and run agent goals such as setup, organize, monitor and suite-status
  • Return results as markdown or JSON
When to use it
Useful when you want a local assistant to triage and organize a Proton mailbox, draft or send mail, audit stored passwords, or manage Proton Drive files without exposing end-to-end encrypted content to a third party.
Requirements
Runs locally over stdio (or streamable HTTP with bearer auth). Needs Node 22 or later, Proton Mail Bridge running locally, and the environment variables PROTON_BRIDGE_HOST, PROTON_IMAP_PORT, PROTON_SMTP_PORT, PROTON_USERNAME and PROTON_PASSWORD (a Bridge-generated app password). Pass features need pass or gopass with gpg; Drive needs the proton-drive CLI logged in.
Before you install
Requires the Bridge app password in PROTON_PASSWORD; the README suggests a JIT wrapper so it is not left on disk. Writes, deletes and credential changes are not executed directly: they create a pending request that must be approved from the user's own terminal, and the identical call must then be repeated. Dry-run is on by default. Pass tools never return secret values. The project is not affiliated with Proton AG.

Installation

In SourceWeft

  1. Open Proton Mail Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Proton Suite Agent

Propósito de este documento

  • Objetivos: Orientar el pulso del repo, el quickstart y el enrutado a los documentos canónicos.
  • Estructura: Ficha → pulso → mapa de lectura → instalación, tools, agente, calidad.
  • Contenido a integrar según contexto: Stack TypeScript/MCP, frontera Bridge, dry-run por defecto, Makefile fachada.

Abrir cuando: Orientación, pulso y enrutado. Aprobado: 15 de agosto de 2026 Audiencia: Agente, Dirección, Usuarios Autoridad: Lectura Clase: Obligatorio Días para revisión: 14 En repo: Sí Estado: Vigente Orden: 1 Propósito: Punto de entrada: pulso, quickstart y qué leer después. Reforma: Operativa Responsable: Alexendros Revisión: 29 de agosto de 2026 Rol: Entrada Ruta: ./README.md

[CI] [CodeQL] [OpenSSF Scorecard] [Coverage] [License: AGPL-3.0] [Node] [npm]

📌

Propósito

Punto de entrada de lectura. Te dice el pulso, cómo arrancar y qué documento abrir después. Lo no negociable vive en CONSTITUTION.md.

Estado en una mirada

Pulso: 24 de septiembre de 2026 · v1.4.0

Fase activa: Fase 1 (Pass / agente / DX) checklist cerrada · siguiente: Fase 2 (Calendar, bloqueada). Ver ROADMAP.md.

Métricas: 47 tools por defecto (50 con Calendar experimental) · 965 tests · cobertura ~98% (gate 95%).

CapaEstado
Mail (Bridge IMAP/SMTP)Operativo
Pass (pass / gopass)Operativo
Drive (proton-drive CLI)Operativo (ADR-006)
CalendarStub hasta CalDAV en Bridge (ADR-005)
Documentación canónicaSubfase 0 completada

MCP server multi-producto para Proton Suite: Mail, Pass, Drive y Calendar (stub). Un agente opera el buzón, gestiona contraseñas y sincroniza archivos — local, sin exfiltrar contenido E2E.

ModoDescripción
stdio (default)Sin exponer red. Ideal para agentes IA locales.
streamable HTTPBearer auth + origin allowlist. Docker / reverse proxy.

Qué leer a continuación

Si necesitasAbreAún no
Lo no negociableCONSTITUTION.mdROADMAP entero
Orden de trabajo y fasesROADMAP.mdCódigo
Implementar como agenteAGENTS.mdARCHITECTURE completo
Capas y flujosARCHITECTURE.mdCódigo
Threat modelSECURITY.md—
Contribuir / PRCONTRIBUTING.md—
Contrato de tools MCPdocs/api/mcp-tools.md—
Decisiones (por qué)docs/adr/—
Índice de guíasdocs/README.md—
Playbooks + promptsplaybooks/README.md—

Primera sesión: este README → AGENTS.md §§ TL;DR + ficha → fase activa en ROADMAP.md → ADR/ancla citada.

Quickstart

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

1. Instalar y compilar

bash
git clone https://github.com/Soluciones-Alexendros/protonsuite-tools.gitcd protonsuite-toolspnpm install && pnpm build && pnpm run smoke

2. Configurar variables de entorno

bash
export [email protected]export PROTON_BRIDGE_PASS=your-bridge-passwordexport [email protected]

3. Conectar tu cliente MCP

jsonc
{  "mcpServers": {    "protonsuite": {      "command": "npx",      "args": ["-y", "@alexendros/protonsuite-agent", "protonsuite-mcp"],      "env": {        "MCP_TRANSPORT": "stdio",        "PROTON_BRIDGE_USER": "[email protected]",        "PROTON_BRIDGE_PASS": "your-bridge-password",        "PROTON_MAIL_FROM": "[email protected]",        "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)

bash
AGENT_DRY_RUN=true pnpm exec protonsuite-agent organize# o: npx -y @alexendros/protonsuite-agent organize

El agente analiza el inbox y presenta un plan sin aplicar cambios. Desactiva AGENT_DRY_RUN solo tras revisión.

Tools MCP

El inventario depende de qué productos estén habilitados: un producto apagado no registra ni anuncia sus herramientas.

ConfiguraciónTools
Por defecto (Mail + Drive)39
+ Pass y Calendar (PROTON_PASS_ENABLED=true, PROTON_CALENDAR_ENABLED=true)47
+ Calendar experimental (PROTON_CALENDAR_EXPERIMENTAL=true)50
Todos los productos apagados5 (solo proton_suite_status y proton_ecosystem_*)

Lectura: response_format: "markdown" | "json".

ProductoToolsResumen
Mail14List, search, read, send, reply, forward, flag, move, delete, attachments
Pass4+List, get (sin valores), generate, health; audit vía agente
Drive8+Status, list, download, upload, share, audit, organize
Calendarstub{available: false} hasta CalDAV vía Bridge (ADR-005)
Suite / Bridge / Ecosystem / AgentrestoEstado unificado, Bridge, binarios, plan de agente

Contrato generado: docs/api/mcp-tools.md. Guía: docs/agent-quickstart.md.

Escribir requiere tu aprobación

Leer no pide nada. Escribir, borrar o tocar credenciales no se ejecuta: el servidor deja una solicitud y te la enseña.

bash
protonsuite-agent pending          # qué espera aprobación, con los campos sensibles tachadosprotonsuite-agent approve <id>     # lo autorizasprotonsuite-agent reject <id>      # lo deniegas

Después de aprobar, repite exactamente la misma llamada. Si cambias un destinatario o una letra del cuerpo, la aprobación ya no vale y habrá que aprobar otra vez.

Aprobar solo se puede desde tu terminal: no hay forma de hacerlo por MCP ni pidiéndoselo al modelo. Detalles en ADR-0009.

Agente

GoalPipeline
setupVerifica Bridge (IMAP + SMTP)
organizeClasifica inbox, carpetas/etiquetas, amenazas
monitor / alertSolo lectura — alertas
pass-auditFortaleza, duplicados y plan de rotación. Solo lectura: nunca escribe en el store.
suite-statusReporte cross-producto
discover / check-imapConectividad
Drive goalsdrive-audit, drive-organize, …

Drive CLI

bash
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-driveproton-drive auth login

Requiere DRIVE_ENABLED=true (default). Ver docs/drive-audit.md.

Despliegue

bash
docker compose up -d

Ver docs/deployment-http-docker.md. Instalador: scripts/install.sh.

Interfaz local

SPA estática en apps/web (ADR-0007): landing y panel de estado. No forma parte del proceso MCP. pnpm run build la genera en apps/web/dist. Se abre sin Bridge; el panel usa el adaptador local «datos de ejemplo» y no pide credenciales. Calendar sigue en stub.

Documentación

DocumentoPara quiénQué cubre
CONSTITUTION.mdTodosNo negociables
ROADMAP.mdDirección / agenteFases y criterios de salida
AGENTS.mdAgentes IAContrato operativo
docs/human-quickstart.mdUsuariosInstalación paso a paso
docs/agent-quickstart.mdAgentes IATools y ejemplos
docs/bridge-core.mdOperadoresBridge headless
docs/deployment-http-docker.mdDevOpsDocker, auth, Pass en compose
docs/local-stdio-secrets.mdOperadoresWrapper JIT
docs/alerting.mdOperadoresWebhook, ntfy, logs
docs/drive-audit.mdOperadoresDrive CLI
ARCHITECTURE.mdDesarrolladoresCapas y flujos
SECURITY.mdAuditoresThreat model
CONTRIBUTING.mdContribuidoresPRs, pnpm, tests
SUPPORT.mdUsuariosCanales de ayuda
CODE_OF_CONDUCT.mdComunidadConducta
docs/Todosarchitecture / guides / runbooks
playbooks/OperadoresWorkflows + prompts

Calidad

Fachada canónica (Makefile): make lint, make test, make smoke, make validate.

bash
make validate        # lint + typecheck + test + build + smokepnpm run typecheck   # TypeScript strictpnpm test            # Vitest (953+)pnpm run coverage    # Coverage v8 — gate 95%, objetivo ≥98%pnpm run build       # tsc → dist/ y SPA apps/web (tokens, contraste, vite)pnpm run smoke       # stdio initialize + tools/listpnpm run knip        # Unused deps/exportspnpm docs:check      # mcp-tools.md en sync

Seguridad (resumen)

  • Bearer timing-safe, origin allowlist, rate-limit 120/min/token.
  • HTTP per-session; idle eviction 30 min.
  • Pass nunca expone valores — solo {found: true}.
  • Dry-run por defecto en el agente (CONSTITUTION.md §4).

Progreso de cobertura

FechaStatementsBranchesTestsNotas
Ago 2026~98%~95%953Subfase 0 + Fase 1
Jul 202698.07%93.63%864Branch hunt
Jun 202661.7%—258Base

Conteo canónico: pnpm test 2>&1 | grep -E 'Test Files|Tests'.

Licencia

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

Ver NOTICE.md para dependencias.

Source: README.md at commit 04f0966

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts