io.github.Alexendros/proton-mail-mcp
Proton Mail MCP via Bridge (IMAP/SMTP) · 13 tools · dual transport stdio + HTTP.
Proton Suite Agent
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: 15 de agosto de 2026 · v1.2.1
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) · 958 tests · cobertura ~98% (gate 95%).
| Capa | Estado |
|---|---|
| Mail (Bridge IMAP/SMTP) | Operativo |
Pass (pass / gopass) | Operativo |
Drive (proton-drive CLI) | Operativo (ADR-006) |
| Calendar | Stub hasta CalDAV en Bridge (ADR-005) |
| Documentación canónica | Subfase 0 |
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 | CONSTITUTION.md | ROADMAP entero |
| Orden de trabajo y fases | ROADMAP.md | Código |
| Implementar como agente | AGENTS.md | ARCHITECTURE completo |
| Capas y flujos | ARCHITECTURE.md | Código |
| Threat model | SECURITY.md | — |
| Contribuir / PR | CONTRIBUTING.md | — |
| Contrato de tools MCP | docs/api/mcp-tools.md | — |
| Decisiones (por qué) | docs/adr/ | — |
| Índice de guías | docs/README.md | — |
| Playbooks + prompts | playbooks/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
git clone https://github.com/Iniciativas-Alexendros/agent-protonsuite.git
cd agent-protonsuite
pnpm install && pnpm build && pnpm 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/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 organize
El agente analiza el inbox y presenta un plan sin aplicar cambios. Desactiva AGENT_DRY_RUN solo tras revisión.
Tools MCP
47 tools por defecto (50 con Calendar experimental). 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 | {available: false} hasta CalDAV vía Bridge (ADR-005) |
| 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.
Agente
| Goal | Pipeline |
|---|---|
setup | Verifica Bridge (IMAP + SMTP) |
organize | Clasifica inbox, carpetas/etiquetas, amenazas |
monitor / alert | Solo lectura — alertas |
pass-audit | Fortaleza, duplicados, plan de rotación (dry-run) |
suite-status | Reporte cross-producto |
discover / check-imap | Conectividad |
| Drive goals | drive-audit, drive-organize, … |
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 login
Requiere DRIVE_ENABLED=true (default). Ver docs/drive-audit.md.
Despliegue
docker compose up -d
Ver docs/deployment-http-docker.md. Instalador: scripts/install.sh.
Documentación
| Documento | Para quién | Qué cubre |
|---|---|---|
CONSTITUTION.md | Todos | No negociables |
ROADMAP.md | Dirección / agente | Fases y criterios de salida |
AGENTS.md | Agentes IA | Contrato operativo |
docs/human-quickstart.md | Usuarios | Instalación paso a paso |
docs/agent-quickstart.md | Agentes IA | Tools y ejemplos |
docs/bridge-core.md | Operadores | Bridge headless |
docs/deployment-http-docker.md | DevOps | Docker, auth, Pass en compose |
docs/local-stdio-secrets.md | Operadores | Wrapper JIT |
docs/alerting.md | Operadores | Webhook, ntfy, logs |
docs/drive-audit.md | Operadores | Drive CLI |
ARCHITECTURE.md | Desarrolladores | Capas y flujos |
SECURITY.md | Auditores | Threat model |
CONTRIBUTING.md | Contribuidores | PRs, pnpm, tests |
playbooks/ | Operadores | Workflows + prompts |
Calidad
pnpm run typecheck # TypeScript strict
pnpm test # Vitest (953+)
pnpm run coverage # Coverage v8 — gate 95%, objetivo ≥98%
pnpm run build # tsc → dist/
pnpm run smoke # stdio initialize + tools/list
pnpm run knip # Unused deps/exports
pnpm 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
| 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.
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @alexendros/proton-mail-mcpSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-alexendros-proton-mail-mcp": {
"command": "npx",
"args": [
"-y",
"@alexendros/proton-mail-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
@alexendros/proton-mail-mcpnpmCompatible MCP Clients
io.github.Alexendros/proton-mail-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.