simple-email-mcp

simple-email-mcp

Un servidor MCP agnóstico al proveedor para correo electrónico (IMAP/SMTP). Funciona con cualquier proveedor de correo — Purelymail, Gmail, Outlook, DomainFactory, o cualquier servidor IMAP/SMTP estándar.

Construido para Claude Desktop, Claude Code, y cualquier cliente compatible con MCP.

Características

• Multi-cuenta — gestiona múltiples cuentas de correo de diferentes proveedores
• Leer, buscar, listar — soporte completo de IMAP con navegación de carpetas
• Enviar correos — texto plano, HTML, o ambos (multipart/alternative)
• Adjuntos — enviar mediante ruta de archivo o datos en línea codificados en base64
• Descargar adjuntos — extraer adjuntos de correos recibidos como base64
• Invitaciones de calendario — enviar invitaciones ICS adecuadas con botones Aceptar/Rechazar
• Guardar en Enviados — guarda automáticamente los correos enviados en la carpeta de Enviados vía IMAP
• Puerta de envío opcional — código de confirmación configurable para prevenir envíos accidentales
• Carpetas internacionales — maneja nombres de carpetas codificados en UTF-7 (alemán, etc.)
• Superficie MCP compacta — una herramienta email con descubrimiento de acciones perezoso para reducir el uso de contexto del cliente

Inicio rápido

1. Instalar

pip install simple-email-mcp

O desde el código fuente:

git clone https://github.com/mexican75/simple-email-mcp.git
cd simple-email-mcp
pip install .

2. Crear accounts.json

{
  "accounts": [
    {
      "name": "personal",
      "address": "me@example.com",
      "password": "your-app-password",
      "provider": "gmail"
    }
  ]
}

3. Añadir a tu cliente

Claude Code (global, todos los proyectos):

claude mcp add email -s user -e ACCOUNTS_FILE=/path/to/accounts.json -- simple-email-mcp

Claude Desktop — añadir a la configuración (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "email": {
      "command": "simple-email-mcp"
    }
  }
}

O si se ejecuta desde el código fuente:

{
  "mcpServers": {
    "email": {
      "command": "python",
      "args": ["/path/to/simple_email_mcp.py"]
    }
  }
}

4. Reinicia tu cliente

Configuración

accounts.json

{
  "send_code": "MYSECRETCODE",
  "accounts": [
    {
      "name": "work",
      "address": "me@company.com",
      "send_as": "alias@company.com",
      "display_name": "Jane Doe",
      "description": "Primary work mailbox",
      "password": "app-password",
      "provider": "outlook"
    },
    {
      "name": "personal",
      "address": "me@gmail.com",
      "password": "app-password",
      "provider": "gmail"
    },
    {
      "name": "custom",
      "address": "me@mydomain.com",
      "password": "password",
      "imap_host": "mail.mydomain.com",
      "imap_port": 993,
      "smtp_host": "mail.mydomain.com",
      "smtp_port": 587,
      "smtp_security": "starttls"
    }
  ]
}

La configuración se recarga en cada llamada a la herramienta, por lo que los cambios en accounts.json como rotar send_code surten efecto sin reiniciar el servidor MCP.

Campos

Campo	Requerido	Descripción
send_code	No	Si se establece, los usuarios deben proporcionar este código para enviar correos. Omitir o establecer a "" para desactivar.
name	Sí	Identificador corto para la cuenta (usado en llamadas a herramientas)
address	Sí	Dirección de correo utilizada para el inicio de sesión IMAP/SMTP
send_as	No	Dirección de alias para usar como dirección From, remitente de sobre SMTP, y dominio de Message-ID. Por defecto es address. El alias debe estar autorizado por tu proveedor de correo.
display_name / from_name	No	Nombre amigable del remitente usado en el encabezado From, p. ej. Jane Doe <alias@example.com>
description	No	Etiqueta legible por humanos mostrada por la acción list_accounts para ayudar a los clientes a elegir el buzón correcto
password	Sí	Contraseña o contraseña específica de la aplicación
provider	No	Preajuste: gmail, outlook, purelymail, domainfactory
imap_host	No	Servidor IMAP personalizado (anula el predeterminado del proveedor)
imap_port	No	Puerto IMAP personalizado (predeterminado: 993)
smtp_host	No	Servidor SMTP personalizado (anula el predeterminado del proveedor)
smtp_port	No	Puerto SMTP personalizado (predeterminado: 465)
smtp_security	No	ssl (puerto 465) o starttls (puerto 587). Se detecta automáticamente desde el puerto si se omite.

Variables de entorno (cuenta única)

En lugar de accounts.json, puedes configurar una sola cuenta mediante variables de entorno:

EMAIL_ADDRESS=me@example.com
EMAIL_PASSWORD=password
IMAP_HOST=imap.example.com
SMTP_HOST=smtp.example.com
SMTP_SECURITY=ssl
SEND_AS=alias@example.com
EMAIL_DISPLAY_NAME="Jane Doe"
EMAIL_DESCRIPTION="Primary mailbox"
SEND_CODE=optional

Herramientas

La versión 2 expone una única herramienta MCP llamada email. Llámala solo con una action para descubrir los parámetros de esa acción, luego llámala de nuevo con params.

{"action": "send"}

{
  "action": "send",
  "params": {
    "account": "work",
    "to": "recipient@example.com",
    "subject": "Hello",
    "body": "Message body"
  }
}

Acción	Descripción
validate_config	Validar configuración sin iniciar sesión en IMAP/SMTP
list_accounts	Listar cuentas configuradas
list_folders	Listar carpetas IMAP para una cuenta
list_emails	Listar correos recientes en una carpeta
search	Buscar correos usando criterios IMAP
read	Leer contenido completo del correo por UID
get_attachment	Descargar un adjunto como base64
prepare_attachments	Inspeccionar rutas de adjuntos locales antes de enviar
save_attachment	Guardar un adjunto directamente en disco (preferido para archivos grandes)
send	Enviar un correo (texto, HTML, adjuntos, invitaciones de calendario)
reply	Responder a un correo (establece automáticamente destinatario, asunto, hilo, cita el cuerpo)
reply_all	Responder a todos (remitente a Para, otros destinatarios a CC, cita el cuerpo)
forward	Reenviar un correo con adjuntos originales
move	Mover un correo entre carpetas
mark	Marcar como leído/no leído/marcado/no marcado

list_accounts devuelve los nombres exactos de las cuentas más cualquier send_as, display_name, y description configurados, para que los clientes puedan usar el token de cuenta explícito en lugar de adivinar coincidencias parciales.

Validación de configuración

Usa validate_config después de editar accounts.json o las variables de entorno. Comprueba campos requeridos, direcciones con formato de correo, puertos, seguridad SMTP, proveedores, y hosts de marcador de posición sin exponer contraseñas ni iniciar sesión en IMAP/SMTP.

{
  "action": "validate_config",
  "params": {}
}

Migración desde v1

La mayoría de los usuarios no necesitan cambiar su configuración de cliente MCP. Mantén el mismo comando simple-email-mcp y reinicia el cliente después de actualizar.

El cambio disruptivo solo afecta a clientes o scripts que llaman nombres exactos de herramientas v1 como email_send_email o email_read_email. En v2, usa la única herramienta email con una acción en su lugar:

Herramienta v1	Acción v2
email_list_accounts	email con action: "list_accounts"
email_send_email	email con action: "send"
email_read_email	email con action: "read"
email_search_emails	email con action: "search"
email_forward	email con action: "forward"
email_reply_all	email con action: "reply_all"

Envío con adjuntos

Solo metadatos de pre-vuelo (recomendado antes de enviar):

attachments: "/path/to/file.pdf, /path/to/doc.xlsx"

Llama a prepare_attachments primero para verificar rutas resueltas, nombres de archivo, tamaños, tipos MIME, y archivos faltantes sin cargar contenidos en el contexto.

Ruta de archivo (cuando el servidor MCP tiene acceso al sistema de archivos):

attachments: "/path/to/file.pdf, /path/to/doc.xlsx"

Base64 en línea (cuando el llamador está en un sandbox):

attachments_inline: [{"filename": "report.pdf", "content_base64": "JVBERi0...", "content_type": "application/pdf"}]

Envío de invitaciones de calendario

Pasa contenido ICS crudo vía calendar_ics. El correo se estructura como multipart/alternative para que los clientes muestren botones Aceptar/Rechazar:

calendar_ics: "BEGIN:VCALENDAR\r\nVERSION:2.0\r\n..."

Puerta de confirmación de envío

Si send_code está establecido en accounts.json, la IA debe mostrar el borrador del correo al usuario y esperar a que proporcionen el código antes de enviar. Esto es útil como punto de control del flujo de trabajo para reducir envíos accidentales.

Importante: esto no es un límite de seguridad estricto si el proceso MCP y el entorno de ejecución de la IA pueden leer la misma fuente de configuración. En esa configuración, la IA podría leer el código de accounts.json o las variables de entorno. Elimina o limpia send_code para desactivar el punto de control.

Pruebas

Ejecuta la suite de regresión desde la raíz del repositorio:

.venv/bin/python -m unittest discover -s tests -v

Seguridad

• Las contraseñas se almacenan en accounts.json — añádelo a .gitignore
• La puerta send_code es un punto de control de intención del usuario, no un secreto estricto, a menos que la IA no pueda leer la fuente de configuración que lo contiene
• No se exponen contraseñas a través de la acción list_accounts
• Adjuntos de archivo: El parámetro attachments lee archivos de rutas que la IA proporciona. Si el servidor MCP se ejecuta con acceso amplio al sistema de archivos, la IA podría teóricamente adjuntar y enviar cualquier archivo legible. Usa attachments_inline (base64) en entornos sandbox, o restringe el acceso al sistema de archivos a nivel de SO/contenedor.
• Guardar adjuntos: save_attachment falla si el archivo de destino ya existe a menos que overwrite=true se establezca explícitamente.

Notas del proveedor

Gmail

Usa una Contraseña de aplicación (no tu contraseña de Google). Habilita IMAP en la configuración de Gmail.

Outlook / Microsoft 365

Usa una Contraseña de aplicación o habilita la autenticación básica para IMAP/SMTP.

Purelymail

Usa tu contraseña de cuenta de Purelymail directamente.

Licencia

MIT — ver LICENCIA

Autores

• Ramon Ramirez (@mexican75)