Proton Mail Bridge MCP y CLI

Proton Mail para Claude Desktop, hecho correctamente.

🌉 Proton Mail Bridge MCP es una integración de Proton Mail local para Claude Desktop y Terminal. Te permite leer, buscar, redactar, enviar, sincronizar y gestionar Proton Mail a través de Proton Bridge, con un servidor MCP completo y una CLI real.

Tras la configuración, Claude Desktop utiliza una instalación local estable de este MCP en tu ordenador. No está limitado a un repositorio, un espacio de trabajo o una carpeta de chat.

Una forma sencilla de entenderlo:

instala Proton Mail Bridge MCP en tu ordenador
conéctalo a Claude Desktop

No necesitas entender los aspectos internos de MCP para usarlo. Si Proton Bridge ya funciona en tu máquina, la configuración es sencilla.

Configuración en 60 segundos

Si Proton Bridge ya funciona en tu máquina:

git clone https://github.com/googlarz/proton-mail-bridge-mcp.git
cd proton-mail-bridge-mcp
npm install
npm run setup:claude-desktop

Luego:

mantén Proton Bridge abierto
reinicia Claude Desktop
abre cualquier chat y comprueba + -> Connectors -> proton-mail-bridge

Si también quieres una comprobación de estado rápida desde la terminal:

npm run check:claude-desktop
proton-mail-bridge doctor --json

Usa los comandos npm run ... que se muestran en este README.

Eso es importante porque los puntos de entrada de la configuración y el instalador residen en la salida compilada dist/, y los scripts de npm ya apuntan a los archivos correctos para ti.

Por qué la gente lo usa

Ponte al día con Proton Mail desde Claude Desktop sin cambiar de herramienta.
Busca facturas, correos electrónicos de viajes, documentos e hilos más rápido.
Redacta, responde, reenvía y envía a través de Proton Bridge.
Usa el mismo backend desde Claude Desktop o directamente desde la Terminal.
Diagnostica problemas de configuración de Claude Desktop y Proton Bridge rápidamente.

Por qué existe esto

Claude tiene un conector nativo de Gmail, pero actualmente no existe un conector nativo de Proton Mail. Este proyecto cierra esa brecha para los usuarios de Proton.

La idea original protonmail-pro-mcp era realmente prometedora, pero la base de código desde la que empecé no era utilizable tal cual. La reconstruí convirtiéndola en un servidor MCP funcional, implementé las piezas que faltaban y añadí una larga lista de mejoras para que sea realmente útil en el día a día.

En qué es bueno:

Soporte real de Proton a través de Proton Bridge.
Operaciones de lectura y escritura: borradores, enviar, responder, reenviar, archivar, papelera, restaurar.
Acceso al contenido de archivos adjuntos y guardado de archivos.
Indexación local, triaje de hilos, vistas de seguimiento y actualización en segundo plano.
Configuración local de Claude Desktop que se vuelve válida para todo el equipo tras la instalación.
Una CLI real para sincronización, búsqueda, lectura, diagnóstico, mantenimiento de Claude Desktop y ejecución completa de herramientas MCP desde la Terminal.

Qué esperar:

Se ejecuta localmente en tu máquina junto a Proton Bridge.
Se conecta a Claude Desktop, pero no es un conector oficial de Claude.
Los enlaces de origen provienen de la capa MCP, no de enlaces nativos de Proton webmail.
Una vez instalado, Claude Desktop puede usarlo en todos tus chats en ese ordenador.

Confianza y seguridad

Se ejecuta localmente en tu máquina.
Se comunica con Proton Mail a través de Proton Bridge en tu máquina.
No requiere un relé de correo alojado ni un servicio de URL remota.
Puede ejecutarse en modo de solo lectura si prefieres valores predeterminados más seguros.
Soporta secretos *_FILE y *_COMMAND si no quieres credenciales sin procesar en la configuración.
Solo realiza envíos o modificaciones de buzón cuando utilizas explícitamente esas capacidades.

Capacidades verificadas

Estas rutas han sido probadas en vivo con una configuración real de Proton Bridge:

Conexión IMAP y listado de carpetas
Conexión SMTP y envío
Lectura completa de mensajes
Indexación local y sincronización incremental
Vistas de hilos, resúmenes y flujos de trabajo de seguimiento
Sincronización de borradores remotos a Borradores de Proton
Listado y guardado de archivos adjuntos
Comandos CLI y llamadas a herramientas MCP genéricas

Qué hace

Conecta Claude a Proton Mail a través de IMAP y SMTP de Proton Bridge.
Lee carpetas, mensajes y archivos adjuntos.
Busca en el correo en vivo y en el correo indexado localmente.
Crea, actualiza, sincroniza y envía borradores.
Envía correos electrónicos, responde y reenvía.
Marca como leído o no leído, destaca o quita estrellas, mueve, archiva, envía a la papelera, restaura y elimina.
Construye un índice SQLite local con puntos de control de sincronización incremental.
Vigila los cambios en el buzón con actualización compatible con IMAP IDLE.
Reconstruye etiquetas e hilos normalizados a partir de datos IMAP.
Clasifica más tipos de archivos adjuntos, incluyendo imágenes en línea, invitaciones de calendario, archivos comprimidos y archivos de firma.
Genera vistas de hilos procesables, resúmenes de bandeja de entrada, candidatos de seguimiento, preparación de reuniones, vistas de búsqueda de documentos y resúmenes de hilos.
Soporta vistas previas de ejecución en seco (dry-run) más seguras para acciones de buzón por lotes y de hilos.
Emite enlaces de recursos MCP y metadatos de origen estructurados para renderizado de estilo de cita posterior.

Bueno saber

Utiliza Proton Bridge. Por qué: este proyecto se conecta a través del acceso IMAP y SMTP local que proporciona Proton Bridge.
Se ejecuta localmente. Por qué: Proton Bridge normalmente se ejecuta en tu propia máquina, por lo que este servidor MCP está diseñado para ejecutarse localmente también.
Los hilos y las etiquetas se reconstruyen a partir de datos IMAP. Por qué: los objetos de hilo y etiqueta nativos de Proton no están disponibles aquí a través de una ruta de conector oficial de Claude.
El manejo de archivos adjuntos es amplio, pero no es magia. Por qué: los casos comunes funcionan bien, incluyendo invitaciones de calendario y archivos adjuntos comunes de documentos/imágenes, pero los formatos MIME de correo electrónico aún pueden ser complicados entre diferentes remitentes y clientes.

Qué falta todavía, y por qué

No hay conector de URL remota listo para usar. Por qué: el producto actual habla con Proton Bridge en tu propia máquina, y Proton Bridge es normalmente local, no un servicio alojado.
No hay flujo de autenticación oficial de Claude ni enlaces profundos nativos de Proton. Por qué: eso requiere soporte a nivel de plataforma de Anthropic y un soporte de proveedor más rico de Proton del que IMAP y SMTP pueden ofrecer.
No hay un modelo de conversación nativo de Proton real. Por qué: este proyecto reconstruye hilos y etiquetas a partir de datos de correo de Bridge en lugar de llamar a una API más rica específica de Proton.
Una experiencia de Proton más nativa sigue siendo posible más adelante. Por qué: si Proton lanza una mejor ruta de integración pública, o una historia de puente local/alojado más limpia, este proyecto puede acercarse a la experiencia nativa de Gmail. Estoy esperando a que ese ecosistema mejore.

Antes de empezar

Necesitarás:

Claude Desktop
Node.js 18 o superior
Una cuenta de Proton
Proton Bridge instalado e iniciada la sesión
Unos 10 minutos

De Proton Bridge, necesitarás:

Host IMAP
Puerto IMAP
Host SMTP
Puerto SMTP
nombre de usuario
Contraseña de Bridge

Para la mayoría de las configuraciones locales de Bridge, los valores predeterminados son:

Host IMAP: 127.0.0.1
Puerto IMAP: 1143
Host SMTP: 127.0.0.1
Puerto SMTP: 1025

🚀 Resumen de configuración

La configuración tiene dos partes:

instalar el servidor MCP local
conectarlo a Claude Desktop

La ruta normal es el asistente de configuración guiada. La ruta manual es solo para personas que desean más control.

Importante:

la carpeta del repositorio solo es necesaria para instalar o actualizar el MCP
Claude Desktop en sí utilizará un tiempo de ejecución estable para todo el equipo después de la configuración
por lo tanto, esto es para el uso general de Claude Desktop en tu ordenador, no solo para una carpeta de proyecto

Parte 1: Instalar Proton Mail Bridge MCP en tu ordenador

1. 🔐 Abrir Proton Bridge

Abre Proton Bridge y asegúrate de que tu cuenta esté conectada.

En Bridge, abre los detalles del buzón o la vista "Configurar cliente de correo" y copia:

Host IMAP y puerto IMAP
Host SMTP y puerto SMTP
nombre de usuario
Contraseña de Bridge

Mantén Proton Bridge abierto. No lo cierres mientras uses este MCP.

2. 📥 Descargar el proyecto

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

Si lo prefieres, también puedes descargar el código fuente desde la última versión de GitHub en lugar de clonar el repositorio.

Si npm no existe en tu máquina, instala Node.js 18+ primero, luego ejecuta los comandos de nuevo.

En este punto, los archivos del servidor MCP están en tu ordenador y listos para el paso de Claude Desktop.

Puedes clonar el repositorio donde quieras. Esta carpeta se utiliza para la instalación y las actualizaciones. Claude Desktop no permanecerá vinculado a esta carpeta después de que finalice la configuración.

Parte 2: Decirle a Claude Desktop que lo use

3. 🪄 Configurar Proton Mail Bridge MCP para Claude Desktop

npm run setup:claude-desktop

Este comando no instala la aplicación Claude Desktop en sí.

Claude Desktop ya debería estar instalado.

Lo que hace este comando es:

comprueba los puertos locales estándar de Proton Bridge
solicita tu nombre de usuario de Proton Bridge y la contraseña de Bridge
utiliza las direcciones locales estándar de Bridge a menos que las sobrescribas
compila este servidor MCP
instala una copia de tiempo de ejecución local estable para Claude Desktop fuera de este repositorio
escribe la entrada de configuración de Claude Desktop que le dice a Claude cómo iniciar ese tiempo de ejecución instalado
almacena los valores PROTONMAIL_* que este servidor MCP necesita dentro de esa configuración local de Claude Desktop
realiza una copia de seguridad de la configuración anterior de Claude Desktop antes de cambiarla

Así que, en lenguaje sencillo:

este comando instala o actualiza la integración de Proton Mail Bridge MCP para Claude Desktop en este ordenador
no instala la aplicación Claude Desktop en sí
no bloquea a Claude en la carpeta desde la que lo ejecutaste

4. 🔁 Reiniciar Claude Desktop

Después de que el asistente finalice:

reinicia Claude Desktop
mantén Proton Bridge abierto
abre cualquier chat en Claude Desktop
haz clic en el botón + cerca del cuadro de chat, luego abre Connectors
confirma que proton-mail-bridge aparece allí y que las herramientas están disponibles
si quieres una segunda comprobación, abre la configuración de desarrollador de Claude Desktop y mira el estado/registros de la conexión MCP

Dónde se instala el tiempo de ejecución estable:

macOS: ~/Library/Application Support/Proton Mail Bridge MCP
Linux: ~/.local/share/proton-mail-bridge-mcp
Windows: %APPDATA%\Proton Mail Bridge MCP

🤖 Cómo funciona esto en Claude Desktop

Si ya tienes Claude Desktop abierto, esto es lo primero que debes saber:

Claude Desktop también admite conectores remotos que solicitan una URL.
Este proyecto no es ese tipo de conector.
Funciona localmente, porque Proton Bridge también funciona localmente en tu máquina.
Por lo tanto, la configuración correcta aquí es el flujo de instalación local de Claude Desktop, no el cuadro de URL remota.

Por qué esto sigue siendo útil:

Gmail obtiene la experiencia más nativa de Claude hoy en día
Los usuarios de Proton aún no tienen esa misma ruta oficial
este proyecto le da a Claude Desktop una integración local práctica de Proton ahora mismo

Por qué no hay una URL remota para pegar:

un conector de URL remota espera un servidor MCP alojado
este proyecto espera llegar a Proton Bridge en tu máquina
Proton Bridge generalmente expone el acceso IMAP/SMTP local en 127.0.0.1
por lo que la configuración más simple y segura es local, no remota

Eso significa que la ruta de Claude Desktop admitida en la versión actual es:

npm run setup:claude-desktop para el flujo guiado sin configuración manual
npm run install:claude-desktop para instalaciones avanzadas o automatizadas de Claude Desktop
npm run update:claude-desktop para actualizar el tiempo de ejecución de Claude Desktop instalado después de actualizar este repositorio
npm run doctor:claude-desktop para confirmar que Claude Desktop sigue apuntando a un tiempo de ejecución de Proton Mail Bridge MCP válido
la pista de extensión local .mcpb documentada en CLAUDE-DESKTOP-PACKAGING.md

🖥️ CLI

También puedes usar Proton Mail Bridge MCP directamente desde la Terminal.

Esto es útil cuando quieres:

probar Proton Bridge sin abrir Claude Desktop
realizar búsquedas o lecturas rápidas con menos pasos
programar sincronizaciones y diagnósticos
verificar que la pila de correo local funciona antes de pedirle a Claude que la use
llamar a toda la superficie de herramientas MCP directamente desde la Terminal

El binario CLI es:

proton-mail-bridge

O, desde el repositorio:

npm run cli -- help

Comandos principales:

proton-mail-bridge status
proton-mail-bridge doctor
proton-mail-bridge sync --folder INBOX --limit 150
proton-mail-bridge search "label:inbox invoice"
proton-mail-bridge search --live --from openai.com
proton-mail-bridge read INBOX::25642
proton-mail-bridge tools
proton-mail-bridge tool get_connection_status
proton-mail-bridge tool search_indexed_emails --args '{"query":"invoice","limit":3}'
proton-mail-bridge claude check
proton-mail-bridge claude install

La mayoría de los comandos también admiten --json para una salida legible por máquina.

Ejemplos prácticos:

# Check whether Proton Bridge and Claude-side wiring are healthy
proton-mail-bridge doctor --json

# Search indexed mail
proton-mail-bridge search "label:inbox invoice" --limit 10

# Read one message
proton-mail-bridge read INBOX::25642

# Call any MCP tool directly from Terminal
proton-mail-bridge tools
proton-mail-bridge tool get_connection_status --json
proton-mail-bridge tool search_indexed_emails --args '{"query":"invoice","limit":3}'

# Check Claude Desktop integration
proton-mail-bridge claude check --json

Si quieres que la CLI llegue a todo lo que expone el servidor MCP, usa:

proton-mail-bridge tools
proton-mail-bridge tool <tool-name> --args '{"key":"value"}'
proton-mail-bridge tool <tool-name> --args-file ./input.json

Eso te da dos formas de usar el mismo sistema:

Claude Desktop lo usa como un servidor MCP
La Terminal lo usa como una CLI, incluyendo llamadas a herramientas MCP genéricas

Ruta sin configuración manual para usuarios de Bridge

Abre la Terminal en la carpeta del proyecto.
Ejecuta:

npm run setup:claude-desktop

Responde a las preguntas para:
- tu nombre de usuario de Proton Bridge
- tu contraseña de Proton Bridge
- si quieres usar los puertos estándar de Bridge locales
- dónde quieres que se almacenen los datos locales
Reinicia Claude Desktop.
Abre Claude y comprueba que las herramientas de Proton Mail Bridge MCP estén disponibles.

Esta es la ruta más fácil porque evita ediciones manuales de JSON y evita la configuración manual de variables de entorno.

Cómo verificar que funcionó:

Abre Claude Desktop.
Inicia o abre un chat.
Haz clic en el botón + cerca del cuadro de mensaje.
Abre Connectors.
Busca proton-mail-bridge.

Si puedes verlo allí, Claude Desktop puede ver este servidor MCP.

Eso significa que está disponible para el uso normal de Claude Desktop en este ordenador, no solo dentro

Proton Mail Bridge MCP