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 en la aplicación web de ChatGPT

• sse para compatibilidad

También corregí un problema de 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

Archivos

• server.py — definiciones de herramientas MCP e inicio de 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 opcionales del proveedor:

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

Configuraciones opcionales del servidor MCP:

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

Los alias también son compatibles 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. Inicie el servidor en modo HTTP:

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

Luego, exponga ese puerto a través de un túnel HTTPS público o un proxy inverso, y registre 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

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

Para una respuesta real, use 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

Use una contraseña de aplicación, no la contraseña de su cuenta principal.

Próximas mejoras razonables

• herramienta de descarga de archivos adjuntos

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

• OAuth en lugar de credenciales basadas en variables de entorno

• pruebas con backends IMAP/SMTP simulados