proton-mcp

Un servidor autohospedado del Model Context Protocol (MCP) para Proton Mail, diseñado para ejecutarse junto a Proton Mail Bridge y exponer un conjunto pequeño y auditable de herramientas de buzón a los clientes MCP.

Estado: desarrollo temprano. v0.1 es intencionalmente de solo lectura.

Objetivos

• Ejecutarse de forma continua en un NAS o servidor doméstico con Docker Compose.

• Mantener Proton Mail Bridge aislado de la LAN y de Internet.

• Comunicarse con Bridge a través de IMAP/SMTP local, en lugar de gestionar el cifrado de Proton directamente.

• Exponer herramientas MCP de alcance limitado en lugar de un acceso genérico al shell o al sistema de archivos.

• Hacer que la limpieza del buzón sea eficiente devolviendo primero los metadatos y el cuerpo completo de los mensajes solo a demanda.

• Añadir acciones de escritura controladas solo después de que la interfaz de solo lectura esté bien probada.

Related MCP server: proton-mail-mcp

Herramientas planificadas para v0.1

• list_folders

• mailbox_stats

• top_senders

• search_mail

• get_message

Consulta docs/SPEC.md para el contrato de las herramientas y ARCHITECTURE.md para el modelo de despliegue.

Modelo de despliegue

MCP client
    |
    | authenticated MCP
    v
proton-mcp container
    |
    | localhost IMAP
    v
proton-bridge container
    |
    v
Proton Mail

El despliegue previsto con Docker Compose proporciona a proton-mcp y proton-bridge un espacio de nombres de red compartido, de modo que Bridge pueda permanecer enlazado a loopback. Los puertos IMAP/SMTP no deben publicarse en la LAN.

Principios de desarrollo

• No se incluye la contraseña de una cuenta de Proton en el repositorio, la imagen, los registros ni las variables de entorno normales.

• No se incluye una herramienta MCP de shell arbitraria.

• No se incluyen herramientas MCP destructivas en v0.1.

• Se prefiere el procesamiento determinista del buzón a enviar grandes volúmenes de contenido de correo a un LLM.

• Se mantiene una validación sencilla: los futuros agentes deberían poder ejecutar un solo comando (make check) antes de finalizar el trabajo.

Documentación

• AGENTS.md — instrucciones concisas para agentes de codificación.

• ARCHITECTURE.md — límites del sistema y decisiones.

• SECURITY.md — invariantes de seguridad.

• docs/SPEC.md — contrato de herramientas MCP.

• docs/DEVELOPMENT.md — flujo de trabajo de desarrollo local.

• docs/OPERATIONS.md — operaciones de Synology / Docker.

Licencia

MIT. Consulta LICENSE.