A
licenseNot graded
qualityD
maintenanceMCP server for the Proton privacy suite — Mail, Pass, Drive, Calendar, and VPN. 36 tools for Claude and other MCP-compatible AI agents.
27
MIT
Proton Suite Agent
An MCP server for the Proton Suite (Mail via Bridge, Drive CLI, Pass, Calendar stub) that lets an AI agent read/organize mail, sync and organize Drive files, and monitor Proton services — with reads free and all writes requiring terminal-side approval.
Mail (read): list folders/labels, mailbox counts (total/unseen/recent), list emails newest-first with pagination, keyword search (by field, date range, sender/recipient, unread), read full email body (text/HTML) plus attachment metadata, download attachment bytes (base64, 10 MB default / 50 MB cap).
Mail (write, approval-gated): send, reply (threaded, reply-all, quote), forward (with attachments), flag/unflag (read, starred, custom), move between mailboxes, delete (trash by default, permanent expunge).
Agent planning:
proton_agent_planproduces a read-only proposed folder/label structure plus severity-graded content alerts (organize / monitor / alert goals) before running the CLI agent.Drive: audit staging inventory (duplicates, obsolete formats), sync status, format report, list remote files, download/upload staging, organize into a type-based layout (dry-run default, no-clobber), move/copy, create folder, remove, share with a Proton user, check auth.
Suite & ecosystem: unified cross-product status, discover installed Proton binaries, health summary, check for updates, install instructions (Bridge/Pass/Drive/GPG).
Bridge: health, combined info+status, version/user/ports, list accounts, login (credentials stay on-machine), logout.
Safety model: read-only tools are annotated and idempotent; write/delete/credential actions never execute directly — they create a pending request you approve or reject in your terminal, and the exact same call must be repeated. Pass never exposes secret values.
Modes: stdio by default (no network) or streamable HTTP with Bearer auth and origin allowlist;
response_formatselectable as markdown/json/concise.
Integrates with Proton Suite, providing tools for Mail (IMAP/SMTP via Bridge), Pass (pass-cli for password management), Drive (CLI for file sync and audit), and Calendar (CalDAV stub). Enables AI agents to manage emails, passwords, files, and calendar events.
Integrates with Proton Mail through the Bridge IMAP/SMTP interface, offering tools to list, search, read, send, reply, forward, flag, move, delete emails, and handle attachments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Proton Suite Agent list my recent unread emails"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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%).
Capa | Estado |
Mail (Bridge IMAP/SMTP) | Operativo |
Pass ( | Operativo |
Drive ( | Operativo (ADR-006) |
Calendar | Stub hasta CalDAV en Bridge (ADR-005) |
Documentación canónica | Subfase 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.
Modo | Descripción |
stdio (default) | Sin exponer red. Ideal para agentes IA locales. |
streamable HTTP | Bearer auth + origin allowlist. Docker / reverse proxy. |
Qué leer a continuación
Si necesitas | Abre | Aún no |
Lo no negociable | ROADMAP entero | |
Orden de trabajo y fases | Código | |
Implementar como agente | ARCHITECTURE completo | |
Capas y flujos | Código | |
Threat model | — | |
Contribuir / PR | — | |
Contrato de tools MCP | — | |
Decisiones (por qué) | — | |
Índice de guías | — | |
Playbooks + prompts | — |
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
git clone https://github.com/Soluciones-Alexendros/protonsuite-tools.git
cd protonsuite-tools
pnpm install && pnpm build && pnpm run smoke2. Configurar variables de entorno
export PROTON_BRIDGE_USER=you@proton.me
export PROTON_BRIDGE_PASS=your-bridge-password
export PROTON_MAIL_FROM=you@proton.me3. 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/passwordo el wrapper JIT enconnectors/stdio-wrapper.sh.examplepara no dejar el bridge password en disco.
4. Organizar el buzón (dry-run)
AGENT_DRY_RUN=true pnpm exec protonsuite-agent organize
# o: npx -y @alexendros/protonsuite-agent organizeEl agente analiza el inbox y presenta un plan sin aplicar cambios. Desactiva AGENT_DRY_RUN solo tras revisión.
Related MCP server: mailpouch
Tools MCP
El inventario depende de qué productos estén habilitados: un producto apagado no registra ni anuncia sus herramientas.
Configuración | Tools |
Por defecto (Mail + Drive) | 39 |
+ Pass y Calendar ( | 47 |
+ Calendar experimental ( | 50 |
Todos los productos apagados | 5 (solo |
Lectura: response_format: "markdown" | "json".
Producto | Tools | Resumen |
14 | List, search, read, send, reply, forward, flag, move, delete, attachments | |
Pass | 4+ | List, get (sin valores), generate, health; audit vía agente |
Drive | 8+ | Status, list, download, upload, share, audit, organize |
Calendar | stub |
|
Suite / Bridge / Ecosystem / Agent | resto | Estado 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.
protonsuite-agent pending # qué espera aprobación, con los campos sensibles tachados
protonsuite-agent approve <id> # lo autorizas
protonsuite-agent reject <id> # lo deniegasDespué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
Goal | Pipeline |
| Verifica Bridge (IMAP + SMTP) |
| Clasifica inbox, carpetas/etiquetas, amenazas |
| Solo lectura — alertas |
| Fortaleza, duplicados y plan de rotación. Solo lectura: nunca escribe en el store. |
| Reporte cross-producto |
| Conectividad |
Drive goals |
|
Drive CLI
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 loginRequiere DRIVE_ENABLED=true (default). Ver docs/drive-audit.md.
Despliegue
docker compose up -dVer 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
Documento | Para quién | Qué cubre |
Todos | No negociables | |
Dirección / agente | Fases y criterios de salida | |
Agentes IA | Contrato operativo | |
Usuarios | Instalación paso a paso | |
Agentes IA | Tools y ejemplos | |
Operadores | Bridge headless | |
DevOps | Docker, auth, Pass en compose | |
Operadores | Wrapper JIT | |
Operadores | Webhook, ntfy, logs | |
Operadores | Drive CLI | |
Desarrolladores | Capas y flujos | |
Auditores | Threat model | |
Contribuidores | PRs, pnpm, tests | |
Usuarios | Canales de ayuda | |
Comunidad | Conducta | |
Todos | architecture / guides / runbooks | |
Operadores | Workflows + prompts |
Calidad
Fachada canónica (Makefile): make lint, make test, make smoke, make validate.
make validate # lint + typecheck + test + build + smoke
pnpm run typecheck # TypeScript strict
pnpm 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/list
pnpm run knip # Unused deps/exports
pnpm docs:check # mcp-tools.md en syncSeguridad (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
Fecha | Statements | Branches | Tests | Notas |
Ago 2026 | ~98% | ~95% | 953 | Subfase 0 + Fase 1 |
Jul 2026 | 98.07% | 93.63% | 864 | Branch hunt |
Jun 2026 | 61.7% | — | 258 | Base |
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.
Available Tools
39 toolsproton_agent_planGet agent organization/alert planARead-onlyIdempotent
Analyzes the mailbox using the embedded agent rules and returns a proposed folder/label structure plus content alerts. This is a read-only planning tool; it does not move, flag or delete emails. Use it before running the CLI agent:organize command.
Inputs: goal, response_format. Returns: alerts, newFolders, labelProposals, folderProposals
proton_bridge_accountsList Bridge accountsARead-onlyIdempotent
Lists all Proton accounts currently configured in Bridge with their connection state.
Inputs: response_format.
proton_bridge_healthBridge health checkARead-onlyIdempotent
Checks if Proton Mail Bridge is running, ports are listening, and IMAP auth works.
Inputs: response_format.
proton_bridge_infoBridge infoARead-onlyIdempotent
Returns Bridge version, user, and connection ports from the CLI.
Inputs: no named parameters.
proton_bridge_loginLogin to BridgeADestructive
Logs in to Proton Mail Bridge using the credentials configured on this machine (PROTON_BRIDGE_PASS or a password-store reference). Takes no arguments: the password never travels through you, and the result contains metadata only.
Inputs: no named parameters.
proton_bridge_logoutLogout from BridgeADestructive
Logs out the current session from Proton Mail Bridge.
Inputs: no named parameters.
proton_bridge_statusBridge full statusARead-onlyIdempotent
Returns combined info + health of the Bridge process in a single call.
Inputs: response_format.
proton_create_folderCreate a mailbox (folder)A
Creates a new IMAP mailbox under the given path (e.g. 'Projects/Afiladocs').
Inputs: path (required).
proton_delete_emailDelete an emailADestructive
Deletes a message. Default mode='trash' moves it to Trash (reversible). mode='permanent' expunges immediately — cannot be undone.
Inputs: uid (required), mode, mailbox, trash_path.
proton_drive_auditAudit Proton Drive contentARead-onlyIdempotent
Scans the staging directory and returns an inventory report: total files, by type/size/date, duplicates, and obsolete formats.
Inputs: staging_dir, response_format. Returns: duplicates, totalBytes, totalFiles, obsoleteFiles
proton_drive_auth_loginAuthenticate with Proton DriveADestructive
Attempts to authenticate with the proton-drive CLI. Since the CLI requires interactive credentials, the tool returns a command the user must run in their terminal.
Inputs: force.
proton_drive_auth_statusProton Drive authentication statusARead-onlyIdempotent
Checks whether the proton-drive CLI is installed and authenticated.
Inputs: response_format.
proton_drive_copyCopy files on Proton DriveC
Copies a remote path using the proton-drive CLI.
Inputs: to (required), from (required).
proton_drive_create_folderCreate folder on Proton DriveCIdempotent
Creates a new folder using the proton-drive CLI.
Inputs: remote_path (required).
proton_drive_downloadDownload from Proton Drive to stagingC
Downloads a remote Proton Drive path into the local staging directory using the proton-drive CLI. Idempotent.
Inputs: local_path, remote_path.
proton_drive_format_reportProton Drive format reportCRead-onlyIdempotent
Detailed analysis of file formats in the staging directory.
Inputs: staging_dir, response_format.
proton_drive_list_filesList files on Proton DriveBRead-onlyIdempotent
Lists the contents of a remote Proton Drive path using the proton-drive CLI. Read-only.
Inputs: remote_path, response_format.
proton_drive_moveMove files on Proton DriveBIdempotent
Moves a remote path using the proton-drive CLI.
Inputs: to (required), from (required).
proton_drive_organizeOrganize files in Proton DriveADestructive
Analyzes the staging directory and moves files into a structured folder layout (by type). Dry-run by default. Never overwrites: colliding destinations are rejected unless strategy="rename".
Inputs: dry_run, strategy, staging_dir.
proton_drive_removeRemove files from Proton DriveADestructiveIdempotent
Permanently removes a remote path from Proton Drive. Destructive operation.
Inputs: remote_path (required).
proton_drive_statusProton Drive sync statusARead-onlyIdempotent
Returns the current state of the proton-drive CLI binary and the local staging directory.
Inputs: response_format.
proton_drive_uploadUpload staging to Proton DriveB
Uploads the local staging directory to a remote Proton Drive path using the proton-drive CLI.
Inputs: local_path, remote_path.
proton_ecosystem_check_updatesCheck for updatesCRead-onlyIdempotent
Available version updates for Proton binaries.
Inputs: product.
proton_ecosystem_discoverDiscover Proton ecosystem binariesBRead-onlyIdempotent
Which Proton product binaries are installed and their auth status.
Inputs: response_format.
proton_ecosystem_healthEcosystem health checkBRead-onlyIdempotent
Unified health status of all Proton ecosystem binaries. Returns a concise pass/fail summary.
Inputs: response_format.
proton_ecosystem_installInstall Proton productDDestructiveIdempotent
Instructions for installing a Proton product binary.
Inputs: product.
proton_flag_emailFlag / unflag emailsAIdempotent
Toggles per-message flags. Supported: 'read', 'unread', 'starred', 'unstarred'. For custom flags, pass add_flags/remove_flags directly.
Inputs: uid (required), action (required), mailbox, add_flags, +1 more.
proton_forward_emailForward an emailC
Forwards an existing message to new recipients. Optionally includes original attachments.
Inputs: to (required), uid (required), html, text, +2 more.
proton_get_attachmentDownload an attachmentARead-onlyIdempotent
Returns the bytes of a specific attachment encoded as base64. Use the attachment index from proton_get_email. Large attachments are truncated to max_bytes (default 10 MB) with a truncated=true flag in the response.
Inputs: uid (required), index (required), mailbox, max_bytes. Returns: base64, filename, truncated, size_bytes, +2 more
proton_get_emailRead one email (full body)ARead-onlyIdempotent
Fetches one email by UID, with headers, text/html body and attachment metadata. Use proton_get_attachment to download attachment bytes. Large HTML bodies are returned as-is — truncate client-side if needed. To mark as read, call proton_flag_email separately (keeps this tool purely read-only).
Inputs: uid (required), mailbox, include_html, response_format. Returns: cc, to, uid, date, +6 more
proton_list_emailsList emails in a mailboxARead-onlyIdempotent
Lists recent emails in a mailbox, newest first. Use pagination with offset+limit. Returns UID, from, to, subject, date, flags, size. Does NOT return the body — use proton_get_email for that.
Inputs: limit, offset, mailbox, response_format. Returns: count, items, total, offset, +3 more
proton_list_foldersList mailboxes (folders/labels)ARead-onlyIdempotent
Lists every IMAP mailbox exposed by Proton Bridge (system folders like INBOX/Sent/Trash and user labels/folders). Use the returned 'path' values as the mailbox argument in other tools. Call this first when the agent doesn't know the mailbox layout.
Inputs: response_format. Returns: folders
proton_mailbox_statusGet mailbox countsARead-onlyIdempotent
Returns total messages, unseen/unread count and recent count for a mailbox. Fast — useful for Routines to check 'do I have unread mail?'.
Inputs: mailbox. Returns: recent, unseen, mailbox, uidNext, +1 more
proton_move_emailMove an email to another mailboxA
Moves a message by UID from one mailbox to another. Use proton_list_folders to see valid targets.
Inputs: uid (required), to_mailbox (required), from_mailbox (required).
proton_reply_emailReply to an emailA
Replies to an existing message preserving threading (In-Reply-To, References). Set reply_all=true to include CC recipients. Set include_quote=true to quote the original.
Inputs: uid (required), html, text, mailbox, +2 more.
proton_search_emailsSearch emailsARead-onlyIdempotent
Keyword-search emails in a mailbox. Filter by text in any field, or restrict to subject/from/to/body. Combine with date range and unseen flag. Returns newest matches first, up to 'limit'. Use 'text' for a broad 'anywhere' match.
Inputs: limit, query, since, before, +6 more. Returns: count, items, mailbox, matched, +1 more
proton_send_emailSend an emailA
Sends an email via Proton Bridge SMTP. 'from' is fixed to the configured address. Provide either text, html, or both. Attachments are base64-encoded bytes.
Inputs: to (required), subject (required), cc, bcc, +4 more.
proton_suite_statusGet Proton Suite unified statusARead-onlyIdempotent
Reports the connection status, diagnostics, and metrics of all configured Proton Suite products.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3/5.0
Scored across 39 tools
Disambiguation3/5
Core mail and Drive actions are mostly distinct, but the set has several overlapping status/health tools: proton_ecosystem_health vs proton_suite_status, proton_bridge_health vs proton_bridge_status vs proton_bridge_info, and proton_drive_auth_status vs proton_drive_status. Descriptions clarify scope, but an agent can still hesitate over which status check to call.
Naming Consistency4/5
Tools consistently use the proton_ prefix and snake_case, generally following a proton_<domain>_<action>_<object> pattern. Minor deviations like proton_bridge_accounts (noun-only) and mixed domain labels (ecosystem/suite/bridge) are readable but slightly less predictable.
Tool Count2/5
39 tools is heavy for a single server, even one spanning mail, Drive, Bridge, and ecosystem administration. Many health/auth/status variants could be consolidated, and the large surface increases selection burden.
Completeness4/5
Mail and Drive lifecycles are broadly covered: listing, reading, sending, replying, forwarding, flagging, moving, deleting, attachments, uploads, downloads, sharing, auditing, and organizing. There are minor gaps such as no folder rename/delete for mail and limited Drive path rename/search, but core workflows are supported.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Programmable email inbox for AI agents — JMAP, PoW auth, stdio MCP server.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Related MCP Servers
- AlicenseAqualityAmaintenanceAn MCP server that gives AI agents permission-gated, audit-logged access to private email providers (Proton Mail via Bridge and plain IMAP), running locally with OAuth-based authentication and human-controlled escalation for destructive operations.6660 npm17MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects to ProtonMail via Bridge, enabling AI assistants like Claude to manage your email.3MIT
- AlicenseAqualityBmaintenanceAn MCP server that enables AI assistants to read and search Proton Mail messages through a locally running Proton Mail Bridge. It provides tools like list_folders, list_messages, search_messages, get_message, and get_attachment.29403 npmMIT