____  ____   ___ _____ ___  _   _   __  __    _    ___ _
 |  _ \|  _ \ / _ \_   _/ _ \| \ | | |  \/  |  / \  |_ _| |
 | |_) | |_) | | | || || | | |  \| | | |\/| | / _ \  | || |
 |  __/|  _ <| |_| || || |_| | |\  | | |  | |/ ___ \ | || |___
 |_|   |_| \_\\___/ |_| \___/|_| \_| |_|  |_/_/   \_\___|_____|
  Bridge Client  ·  CLI + Claude Desktop MCP for Proton Mail

Cliente de Proton Mail Bridge

Un cliente CLI y MCP para Claude Desktop con todas las funciones para Proton Mail, construido sobre Proton Bridge.

Acerca de

El cliente de Proton Mail Bridge le ofrece dos formas de utilizar Proton Mail mediante programación:

CLI: un cliente de terminal con paridad total con la superficie MCP. Lea, busque, envíe, redacte, archive, gestione carpetas, clasifique hilos y ejecute diagnósticos, todo desde la línea de comandos. El cuerpo del mensaje se puede enviar a través de stdin. La salida es legible por humanos o --json.

Servidor MCP: las mismas capacidades expuestas como un servidor del Protocolo de Contexto de Modelo (MCP) para que Claude Desktop pueda leer y gestionar su Proton Mail en cualquier chat, en la misma máquina donde se ejecuta Proton Bridge.

Ambas superficies comparten el mismo backend: IMAP y SMTP de Proton Bridge, un índice local de SQLite y un registro de auditoría. Sin retransmisión alojada, sin URL remota, sin dependencia de la nube más allá de su propia cuenta de Proton.

Requisitos previos

• Node.js 18+

• Proton Bridge instalado y con sesión iniciada

• Desde Bridge: host/puerto IMAP, host/puerto SMTP, nombre de usuario, contraseña de Bridge

Direcciones locales predeterminadas de Bridge: IMAP 127.0.0.1:1143, SMTP 127.0.0.1:1025

Instalación

git clone https://github.com/googlarz/proton-mail-bridge-client.git
cd proton-mail-bridge-client
npm install
npm run build

Después de la instalación, el binario proton-mail-bridge-client (y proton-mail-bridge) estará disponible desde el repositorio.

Para una instalación en todo el sistema: npm install -g .

CLI

proton-mail-bridge-client <command> [options]

Todos los comandos admiten --json para una salida legible por máquina.

Leer

proton-mail-bridge-client emails --folder INBOX --limit 25
proton-mail-bridge-client read INBOX::25642
proton-mail-bridge-client search "invoice" --limit 10
proton-mail-bridge-client search --live --from openai.com
proton-mail-bridge-client attachments INBOX::25642

Clasificar

proton-mail-bridge-client digest
proton-mail-bridge-client threads "quarterly review"
proton-mail-bridge-client actionable
proton-mail-bridge-client followups
proton-mail-bridge-client thread-brief <threadId>
proton-mail-bridge-client document-threads --category invoice
proton-mail-bridge-client meeting-context alice@example.com

Redactar y enviar

proton-mail-bridge-client send --to bob@example.com --subject "Hey" --body "Hello"
echo "Hello" | proton-mail-bridge-client send --to bob@example.com --subject "Hey"
proton-mail-bridge-client reply INBOX::25642 --body "On it."
proton-mail-bridge-client reply INBOX::25642 --reply-all --body "On it."
proton-mail-bridge-client forward INBOX::25642 --to carol@example.com

Acciones de buzón

proton-mail-bridge-client move INBOX::25642 Folders/Archive
proton-mail-bridge-client archive INBOX::25642
proton-mail-bridge-client trash INBOX::25642
proton-mail-bridge-client restore Trash::25642
proton-mail-bridge-client mark-read INBOX::25642
proton-mail-bridge-client mark-read INBOX::25642 --unread
proton-mail-bridge-client star INBOX::25642
proton-mail-bridge-client delete INBOX::25642
proton-mail-bridge-client batch archive INBOX::100,INBOX::101,INBOX::102
proton-mail-bridge-client thread-action <threadId> archive

Carpetas

proton-mail-bridge-client folders
proton-mail-bridge-client create-folder Folders/Receipts
proton-mail-bridge-client rename-folder Folders/Receipts Folders/Bills
proton-mail-bridge-client delete-folder Folders/Bills

Borradores

proton-mail-bridge-client drafts
proton-mail-bridge-client draft-create --to bob@example.com --subject "Draft" --body "..."
proton-mail-bridge-client draft-read <id>
proton-mail-bridge-client draft-update <id> --subject "Updated subject"
proton-mail-bridge-client draft-reply INBOX::25642 --body "Will do."
proton-mail-bridge-client draft-forward INBOX::25642 --to carol@example.com
proton-mail-bridge-client draft-sync <id>
proton-mail-bridge-client draft-send <id>
proton-mail-bridge-client draft-delete <id>
proton-mail-bridge-client remote-drafts

Análisis y diagnósticos

proton-mail-bridge-client stats
proton-mail-bridge-client analytics
proton-mail-bridge-client contacts
proton-mail-bridge-client volume-trends --days 14
proton-mail-bridge-client watch --timeout 30
proton-mail-bridge-client test-email you@example.com
proton-mail-bridge-client doctor
proton-mail-bridge-client status
proton-mail-bridge-client sync --folder INBOX --limit 150

Paso a través de herramientas MCP

Cualquier herramienta MCP también se puede llamar directamente desde la CLI:

proton-mail-bridge-client tools
proton-mail-bridge-client tool get_connection_status --json
proton-mail-bridge-client tool search_indexed_emails --args '{"query":"invoice","limit":3}'

Entorno

Tanto la CLI como el servidor MCP leen las mismas variables de entorno:

export PROTONMAIL_USERNAME='you@proton.me'
export PROTONMAIL_PASSWORD='your-bridge-password'
export PROTONMAIL_IMAP_HOST='127.0.0.1'
export PROTONMAIL_IMAP_PORT='1143'
export PROTONMAIL_IMAP_SECURE='false'
export PROTONMAIL_SMTP_HOST='127.0.0.1'
export PROTONMAIL_SMTP_PORT='1025'
export PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-client"

Secretos opcionales mediante archivo o comando (evita credenciales sin formato en el shell):

export PROTONMAIL_USERNAME_FILE='/path/to/user.txt'
export PROTONMAIL_PASSWORD_FILE='/path/to/pass.txt'
# or
export PROTONMAIL_USERNAME_COMMAND='pass proton/username'
export PROTONMAIL_PASSWORD_COMMAND='pass proton/password'

Flags de tiempo de ejecución completos:

export PROTONMAIL_READ_ONLY='false'
export PROTONMAIL_ALLOW_SEND='true'
export PROTONMAIL_ALLOW_REMOTE_DRAFT_SYNC='true'
export PROTONMAIL_ALLOWED_ACTIONS='mark_read,mark_unread,star,unstar,archive,trash,restore'
export PROTONMAIL_AUTO_SYNC='true'
export PROTONMAIL_STARTUP_SYNC='true'
export PROTONMAIL_SYNC_INTERVAL_MINUTES='5'
export PROTONMAIL_IDLE_WATCH='true'
export PROTONMAIL_IDLE_MAX_SECONDS='30'

Configuración de Claude Desktop

Para usar el cliente de Proton Mail Bridge con Claude Desktop, ejecute el asistente guiado:

npm run setup:claude-desktop

Esto hará lo siguiente:

• comprobará los puertos de su Bridge local

• solicitará su nombre de usuario y contraseña de Bridge

• compilará el proyecto

• instalará un tiempo de ejecución estable para toda la máquina

• escribirá la entrada de configuración de MCP de Claude Desktop

Después de la configuración: reinicie Claude Desktop, mantenga Proton Bridge abierto y luego verifique + → Connectors → proton-mail-bridge.

El tiempo de ejecución se instala en:

• macOS: ~/Library/Application Support/Proton Mail Bridge Client

• Linux: ~/.local/share/proton-mail-bridge-client

• Windows: %APPDATA%\Proton Mail Bridge Client

Actualización

git pull
npm run update:claude-desktop

Configuración manual de Claude Desktop

{
  "mcpServers": {
    "proton-mail-bridge": {
      "command": "node",
      "args": ["/path/to/runtime/dist/index.js"],
      "cwd": "/path/to/runtime",
      "env": {
        "PROTONMAIL_USERNAME": "you@proton.me",
        "PROTONMAIL_PASSWORD": "your-bridge-password",
        "PROTONMAIL_IMAP_HOST": "127.0.0.1",
        "PROTONMAIL_IMAP_PORT": "1143",
        "PROTONMAIL_IMAP_SECURE": "false",
        "PROTONMAIL_SMTP_HOST": "127.0.0.1",
        "PROTONMAIL_SMTP_PORT": "1025"
      }
    }
  }
}

Nota sobre macOS

En macOS, better-sqlite3 debe ser un binario nativo compilado para la máquina actual. El instalador maneja esto automáticamente. Si restaura desde otro entorno o ve un bloqueo de módulo nativo, ejecute npm run update:claude-desktop.

Confianza y seguridad

• Se ejecuta completamente de forma local: sin retransmisión alojada, sin URL remota.

• Se comunica con Proton Mail solo a través de Proton Bridge en su propia máquina.

• PROTONMAIL_READ_ONLY=true deshabilita todas las operaciones de escritura.

• PROTONMAIL_ALLOW_SEND=false deshabilita los envíos SMTP sin afectar otras escrituras.

• PROTONMAIL_ALLOWED_ACTIONS controla qué mutaciones de buzón están permitidas.

• batch_email_action y apply_thread_action admiten dryRun: true.

• Admite secretos *_FILE y *_COMMAND para que las credenciales sin formato nunca aparezcan en la configuración o en el historial del shell.

• Las carpetas del sistema (INBOX, Sent, Trash, Spam, Archive, All Mail) están protegidas contra la eliminación accidental.

Comparación con el conector nativo de Gmail de Claude

Superficie de herramientas

Enviar

send_email · send_test_email · reply_to_email · forward_email

Borradores

create_draft · create_reply_draft · create_forward_draft · create_thread_reply_draft · list_drafts · list_remote_drafts · get_draft · update_draft · sync_draft_to_remote · send_draft · delete_draft

Leer

get_emails · get_email_by_id · search_emails · list_attachments · get_attachment_content · save_attachments · save_attachment

Clasificar

get_folders · sync_folders · get_labels · get_threads · get_thread_by_id · get_thread_brief · get_actionable_threads · get_inbox_digest · get_follow_up_candidates · find_document_threads · prepare_meeting_context

Acciones

mark_email_read · star_email · move_email · archive_email · trash_email · restore_email · delete_email · batch_email_action · apply_thread_action

Gestión de carpetas

create_folder · rename_folder · delete_folder

Análisis

get_email_stats · get_email_analytics · get_contacts · get_volume_trends

Diagnósticos

get_connection_status · get_runtime_status · run_doctor · get_audit_logs · run_background_sync · wait_for_mailbox_changes · sync_emails · get_index_status · search_indexed_emails · clear_cache · clear_index · get_logs

Notas operativas

• get_emails y search_emails devuelven un emailId compuesto: úselo para lecturas y acciones.

• El índice local se encuentra en PROTONMAIL_DATA_DIR/mail-index.sqlite.

• Los registros de auditoría se encuentran en PROTONMAIL_DATA_DIR/audit.log.

• La sincronización en segundo plano y IMAP IDLE mantienen el índice actualizado, pero dependen de que Bridge permanezca activo.

• search_indexed_emails admite atajos from:, to:, subject:, label:, domain:.

• La sincronización de borradores es de mejor esfuerzo: el borrador local siempre se conserva incluso si la sincronización remota falla.

Licencia

MIT