email-mcp

Pequeño servidor MCP personal para un único buzón a través de IMAP + SMTP.

Está orientado principalmente a una configuración privada:

• un buzón

• credenciales suministradas a través de variables de entorno

• lectura de correo mediante IMAP

• envío de correo mediante SMTP

• funciona bien con los valores predeterminados de Yandex Mail, pero puede apuntar a cualquier proveedor IMAP/SMTP

Qué he cambiado

Este repositorio originalmente funcionaba solo en modo stdio. Eso está bien para clientes MCP locales, pero la integración web de ChatGPT necesita un endpoint MCP HTTP. El servidor ahora admite:

• stdio para uso local/desarrollo

• streamable-http para uso con la aplicación web de ChatGPT

• sse para compatibilidad

También corregí un problema con los hilos de correo:

• el antiguo parámetro reply_to solo configuraba la cabecera Reply-To

• las respuestas reales normalmente deberían usar In-Reply-To y References

• read_email ahora devuelve esas cabeceras para que puedan pasarse de vuelta a send_email

Y mejoré la salida de read_email devolviendo:

• cabeceras decodificadas

• metadatos de archivos adjuntos

• cabeceras de hilos de mensajes

Related MCP server: IMAP/SMTP Email MCP Server

Soporte para archivos adjuntos

Esta versión admite tanto la lectura como el envío de archivos adjuntos.

Descargar un archivo adjunto de un correo recibido

1. Llama a read_email(uid=..., folder="INBOX")

2. Inspecciona la lista attachments

3. Usa attachment_index con get_attachment(...)

get_attachment(...) devuelve:

• filename

• content_type

• size_bytes

• content_base64

Enviar archivos adjuntos en un correo saliente

send_email(...) acepta una lista de attachments.

Cada elemento puede ser uno de:

{"path": "/path/to/file.pdf"}

{"filename": "note.txt", "content_text": "hello from MCP"}

{"filename": "report.pdf", "content_base64": "JVBERi0x...", "content_type": "application/pdf"}

Comportamiento de la carpeta de enviados

Después de que el envío SMTP tiene éxito, el mismo mensaje MIME se añade a tu carpeta de enviados IMAP.

Por defecto, ese nombre de carpeta es:

Sent

Puedes sobrescribirlo si tu buzón utiliza un nombre de carpeta IMAP diferente:

export SENT_FOLDER="Sent"
# or
export MAILBOX_SENT_FOLDER="Sent"

Si el correo enviado no aparece, primero ejecuta list_folders() y utiliza el nombre exacto de la carpeta devuelto por tu buzón.

Archivos

• server.py — definiciones de herramientas MCP e inicio del transporte

• mail_ops.py — implementación de IMAP/SMTP

• requirements.txt — dependencias de Python

Entorno

Requerido:

export MAILBOX_EMAIL="you@example.com"
export MAILBOX_PASSWORD="your-app-password"

Configuraciones de proveedor opcionales:

export IMAP_HOST="imap.yandex.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yandex.com"
export SMTP_PORT="465"

Configuración opcional de la carpeta de enviados:

export SENT_FOLDER="Sent"

Configuraciones opcionales del servidor MCP:

export MCP_TRANSPORT="stdio"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"

También se admiten alias por conveniencia:

export YANDEX_EMAIL="you@yandex.ru"
export YANDEX_APP_PASSWORD="..."

Instalación

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Ejecutar localmente con stdio

python server.py

Este es el modo correcto para clientes MCP locales que inician el proceso directamente.

Ejecutar para la aplicación web de ChatGPT

La web de ChatGPT necesita un endpoint MCP HTTPS público. Inicia el servidor en modo HTTP:

python server.py --transport streamable-http --host 0.0.0.0 --port 8000

Luego, expón ese puerto a través de un túnel HTTPS público o un proxy inverso, y registra la URL MCP resultante en ChatGPT.

Herramientas expuestas

list_folders()

Enumera las carpetas IMAP disponibles.

search_emails(folder="INBOX", text=None, unseen_only=False, since_date=None, limit=30)

Busca mensajes según criterios IMAP.

Devuelve elementos como:

• uid

• subject

• from

• to

• date

• flags

• size_bytes

read_email(uid, folder="INBOX")

Obtiene un mensaje completo sin marcarlo como leído.

Devuelve:

• cabeceras decodificadas

• message_id

• in_reply_to

• references

• attachments

• body_plain

• body_html

get_attachment(uid, folder="INBOX", attachment_index=None, filename=None)

Obtiene un único archivo adjunto y lo devuelve en base64.

send_email(...)

Envía un mensaje a través de SMTP.

Parámetros importantes:

• reply_to_header — establece la cabecera Reply-To

• in_reply_to — cabecera de hilos

• references — cabecera de hilos

• attachments — lista opcional de especificaciones de archivos adjuntos

Para una respuesta real, usa in_reply_to y normalmente también references.

Notas sobre Yandex

Los valores predeterminados típicos de Yandex son:

• IMAP: imap.yandex.com:993 sobre SSL/TLS

• SMTP: smtp.yandex.com:465 sobre SSL/TLS

Usa una contraseña de aplicación, no la contraseña de tu cuenta principal.

Próximas actualizaciones razonables

• archivos adjuntos de imágenes en línea/incrustadas

• límites de tamaño de archivos adjuntos y streaming

• herramientas de mover/archivar/eliminar con confirmación

• OAuth en lugar de credenciales basadas en variables de entorno

• pruebas con backends IMAP/SMTP simulados