mcp4mail

npx add-mcp 'https://mcp4mail.online/mcp'

mcp4mail

Tu buzón de correo como un servidor MCP. Conecta una cuenta IMAP y deja que tu asistente de IA lea y busque en tu correo, autorizado mediante OAuth 2.1. Alojado en mcp4mail.online, de código abierto y autoalojable.

Ejecútalo tú mismo y tus credenciales nunca salen de tu máquina. Un conector de correo alojado necesariamente guarda tu contraseña IMAP en el servidor de otra persona; con mcp4mail puedes mantenerla en tu propia base de datos. Un solo docker compose up te lleva allí: consulta la guía de autoalojamiento.

Primeros días: el endpoint MCP lista tus cuentas conectadas; leer y buscar correo es lo siguiente.

Este proyecto es desarrollado principalmente por desarrolladores de IA orquestados a través de mcptask.online. Observa el desarrollo en vivo: https://mcptask.online/live

Cómo se construye este proyecto

Este es un producto real de código abierto y, al mismo tiempo, una demostración pública. Las tareas son escritas por personas en mcptask.online, recogidas por runners (Claude Code impulsado por el runner de mcptask, en nuestras propias máquinas), y cada cambio sigue el mismo camino: tarea → rama → pull request → pruebas y CI → fusión → despliegue en mcp4mail.online. Nadie, persona o runner, hace push a main directamente: la rama está protegida por un conjunto de reglas del repositorio que requiere un pull request abierto, un historial lineal y comprobaciones de estado en verde (escaneos de seguridad, lint, pruebas unitarias, pruebas de sistema) antes de que se permita una fusión squash.

Míralo en vivo: https://mcptask.online/live

Dónde mirar si quieres verificar todo esto por ti mismo: la pestaña Pull requests, donde cada PR enlaza su tarea y muestra sus ejecuciones de CI, incluidas las fallidas; CLAUDE.md y .claude/, las instrucciones desde las que trabajan los runners; y la configuración de CI.

Las personas aún escriben los resúmenes de tareas, revisan los pull requests y deciden qué se publica y qué no; un runner ejecuta una tarea de principio a fin, pero no decide qué construir. Un runner es un usuario con un asiento aquí, no algo gratuito o ilimitado.

Herramientas MCP

Herramienta	Qué hace
list_mail_accounts	Lista las cuentas de correo que has conectado, con los ids que usan las otras herramientas.
get_mail_account	Muestra los detalles de conexión de una cuenta (nunca su contraseña).
list_folders	Lista las carpetas de una cuenta.
search_messages	Busca por asunto, remitente, destinatarios, nombres de archivos adjuntos y fecha.
get_message	Lee un mensaje.
get_attachment	Descarga un adjunto de un mensaje: un enlace de corta duración, o con inline: true el archivo en sí (hasta 5 MB) dentro de la respuesta MCP.
search_contacts	Encuentra direcciones con las que has mantenido correspondencia.
get_outgoing_status	Indica si un correo entregado a send_message ha salido.
set_flags	Marca un mensaje o lo marca como leído / no leído. Escritura.
move_message	Mueve un mensaje a otra carpeta. Escritura.
trash_message	Mueve un mensaje a la Papelera. Escritura.
create_folder	Crea una carpeta. Escritura.
create_draft	Guarda un borrador. Escritura.
send_message	Prepara un correo; se envía solo después de que lo apruebes. Escritura.

Las herramientas de escritura funcionan solo en un buzón cuyo propietario activó "Permitir que la IA haga cambios en este buzón" y marcó lo que hace la herramienta; en cualquier otro lugar se rechazan, consulta a continuación. send_message nunca envía por sí solo: recibes un correo con un enlace y el mensaje sale solo cuando pulsas Enviar.

Autoalojamiento

cp .env.example .env    # fill in the values
docker compose up -d

Lee docs/self-hosting.md primero: qué variables de entorno importan, por qué HITCH_RESOURCE_URI debe coincidir exactamente con tu URL pública, TLS y cómo se almacenan las contraseñas del buzón.

Stack

Ruby 3.4, Rails 8.1, PostgreSQL, Hotwire (Turbo + Stimulus), Tailwind CSS, Solid Queue / Cache / Cable.

Desarrollo

bin/setup   # install gems, prepare the database, start the dev server
bin/dev     # web server + Tailwind watcher
bin/ci      # rubocop, security audits, tests, system tests

PostgreSQL debe estar ejecutándose localmente; la configuración predeterminada se conecta a través del socket local como tu usuario del sistema operativo.

Secretos

Este repositorio es público. Nunca se confirma nada secreto: config/master.key, .env* y credentials.yml están ignorados por git, los secretos de producción provienen del entorno.

Las contraseñas del buzón se cifran en reposo con Active Record Encryption. En producción, genera claves con bin/rails db:encryption:init y provéelas a través de las credenciales cifradas (active_record_encryption.*) o las variables de entorno ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY y ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT. El desarrollo y las pruebas derivan claves desechables del tmp/local_secret.txt específico de cada máquina.

Cuentas de correo

mcp4mail se conecta a tu buzón mediante IMAP simple con un nombre de usuario y contraseña. Usa una contraseña específica de aplicación siempre que tu proveedor la ofrezca (Gmail, iCloud, Fastmail, Outlook.com, Yahoo y otros la ofrecen), para que lo que se almacena en la base de datos pueda revocarse por sí solo y no sea la clave de toda tu cuenta. Gmail se admite de la misma manera: activa la verificación en dos pasos e inicia sesión con una contraseña de aplicación. En una cuenta de Google Workspace, el administrador puede desactivar IMAP o las contraseñas de aplicación, y solo ellos pueden volver a activarlas. Cómo se almacena la contraseña y quién puede descifrarla se describe en las notas de seguridad de la guía de autoalojamiento.

Endpoint MCP: solo lectura por diseño

Cada buzón es de solo lectura hasta que digas lo contrario. Cada buzón en la página de Cuentas de correo tiene un interruptor, "Permitir que la IA haga cambios en este buzón", y está desactivado por defecto.

• Desactivado (el predeterminado): la IA solo puede leer y buscar. Cualquier herramienta que cambiaría el buzón se rechaza con un mensaje que le dice al modelo que el buzón es de solo lectura, y el rechazo se escribe en el registro de auditoría como denied.
• Activado: las casillas de verificación se despliegan bajo el interruptor y marcas lo que la IA puede hacer en ese buzón: marcar como leído y marcar con bandera (set_flags), mover mensajes y crear carpetas (move_message, create_folder), escribir borradores (create_draft), enviar y responder, siempre después de tu aprobación (send_message), eliminar a la papelera (trash_message). Todas están marcadas cuando lo activas. Una herramienta cuya casilla no está marcada se rechaza de la misma manera que en un buzón de solo lectura. list_mail_accounts y get_mail_account le dicen al modelo qué puede hacer.

El registro de herramientas se niega a arrancar con una herramienta que no sea ni de solo lectura ni no destructiva ni esté explícitamente declarada como herramienta de escritura (write_tool destructive: ..., permission: ... en McpTools::ApplicationTool, donde permission es una de las casillas anteriores), para que nada pueda colarse como herramienta de escritura por accidente. Las herramientas de escritura anuncian readOnlyHint: false y declaran su propio destructiveHint.

Qué significa y qué no significa solo lectura, claramente:

• Nada puede cambiar un buzón sin su interruptor y la casilla correspondiente. Las carpetas se abren con IMAP EXAMINE, por lo que incluso leer no marca los mensajes como vistos.

• Sí lee tu correo, siempre que un cliente de IA que hayas conectado lo solicite. Conecta solo clientes en los que confíes para eso.

• Mantiene una copia de los encabezados de los mensajes (remitente, destinatarios, asunto, fecha, banderas, tamaño) en su propia base de datos, actualizada cada 15 minutos, para que las búsquedas no golpeen tu servidor de correo cada vez.

• Alcance. Cada herramienta resuelve los datos a través de las propias cuentas de correo del usuario con sesión iniciada; un id de cuenta que no sea suyo se rechaza antes de que se ejecute cualquier código de herramienta.

• Límites de velocidad. Hitch limita cada par usuario + cliente (120 solicitudes por minuto); además, cada usuario tiene una cuota para llamadas de herramientas en todos sus clientes (240 por minuto).

• Registro de auditoría. Cada llamada se escribe en mcp_audit_events: usuario, cliente, herramienta, cuenta, resultado, filas devueltas, duración. Los argumentos no se almacenan.

• Protección de búsqueda. Las páginas están limitadas a 50 resultados, y cada cuenta tiene un presupuesto de búsquedas (60 por 10 minutos) y filas devueltas (1,000 por hora), para que un bucle descontrolado no pueda recorrer todo un buzón.

Contribuciones

Consulta CONTRIBUTING.md. bin/ci debe pasar.

Licencia

MIT