Email MCP for Gmail, iCloud and microsoft

@marlinjai/email-mcp

Un servidor MCP unificado para acceso a correo electrónico en Gmail, Outlook, iCloud y proveedores IMAP genéricos.

Características

• Soporte multi-proveedor -- Gmail (API REST), Outlook (Microsoft Graph), iCloud (IMAP) y proveedores IMAP/SMTP genéricos
• Autenticación OAuth2 -- Flujos OAuth basados en navegador para Gmail y Outlook, con renovación automática de tokens
• Cliente de correo completo -- Buscar, leer, enviar, responder, reenviar, organizar y gestionar borradores
• Operaciones por lotes -- Eliminar, mover o marcar cientos de correos en una sola llamada
• Búsqueda ligera -- Resultados de búsqueda compactos por defecto (~20KB vs ~1.4MB) con recuperación opcional del cuerpo completo
• Almacenamiento de credenciales cifrado -- Cifrado AES-256-GCM en reposo con claves derivadas de la máquina
• APIs nativas del proveedor -- Usa la API de Gmail y Microsoft Graph cuando estén disponibles para funciones más ricas, y recurre a IMAP para compatibilidad universal

Instalación

Instala globalmente desde npm:

npm install -g @marlinjai/email-mcp

O ejecuta directamente con npx (sin necesidad de instalación):

npx @marlinjai/email-mcp

Inicio rápido

1. Ejecuta el asistente de configuración interactivo para añadir tus cuentas de correo:

npx @marlinjai/email-mcp setup

El asistente te guiará a través de la selección del proveedor y la autenticación. Después de cada cuenta, pregunta si deseas añadir otra, para que puedas configurar Gmail, Outlook e iCloud de una sola vez.

2. Añade el servidor a tu configuración de MCP (.mcp.json):

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}

3. Comienza a usar las herramientas de correo en Claude Code: busca en tu bandeja de entrada, envía correos, organiza mensajes y más.

Guías de configuración de proveedores

Gmail

No se necesita configuración: el asistente de configuración maneja todo usando credenciales OAuth integradas (PKCE):

npx @marlinjai/email-mcp setup
# Select "Gmail" when prompted
# A browser window opens for Google authorization
# Grant the requested permissions and return to the terminal

Nota: Si prefieres usar tu propia aplicación OAuth, crea un Cliente de OAuth 2.0 de escritorio en la Consola de Google Cloud con la API de Gmail habilitada.

Outlook

No se necesita configuración: el asistente de configuración maneja todo usando credenciales OAuth integradas (PKCE):

npx @marlinjai/email-mcp setup
# Select "Outlook" when prompted
# A browser window opens for Microsoft authorization
# Sign in and grant the requested permissions

Nota: Si prefieres usar tu propia aplicación OAuth, regístrala en el Portal de Azure con los permisos Mail.ReadWrite, Mail.Send y offline_access.

iCloud

1. Ve a appleid.apple.com e inicia sesión.
2. Navega a Contraseñas específicas de la aplicación y genera una nueva contraseña.
3. Ejecuta el asistente de configuración:

npx @marlinjai/email-mcp setup
# Select "iCloud" when prompted
# Enter your iCloud email address
# Enter the app-specific password you generated

IMAP genérico

Ejecuta el asistente de configuración con los detalles de tu servidor IMAP/SMTP:

npx @marlinjai/email-mcp setup
# Select "Other IMAP" when prompted
# Enter your IMAP host, port, and credentials
# Optionally enter SMTP host and port for sending

Herramientas disponibles (25)

Gestión de cuentas (4)

Herramienta	Descripción
email_list_accounts	Lista todas las cuentas configuradas con el estado de conexión
email_add_account	Añade una nueva cuenta IMAP o iCloud (Gmail/Outlook requieren el asistente de configuración)
email_remove_account	Elimina una cuenta y sus credenciales almacenadas
email_test_account	Prueba la conexión a una cuenta

Lectura y búsqueda (5)

Herramienta	Descripción
email_list_folders	Lista todas las carpetas/etiquetas de una cuenta
email_search	Busca correos con filtros. Devuelve resultados compactos por defecto (returnBody=false). Establece returnBody=true para incluir los cuerpos completos de los correos
email_get	Obtiene el contenido completo del correo por ID (cabeceras, cuerpo, metadatos de adjuntos)
email_get_thread	Obtiene un hilo/conversación de correo completo
email_get_attachment	Descarga un adjunto específico por ID (devuelve datos en base64)

Envío y borradores (5)

Herramienta	Descripción
email_send	Redacta y envía un nuevo correo (para, cc, cco, asunto, cuerpo)
email_reply	Responde a un correo (admite responder a todos, conserva el hilo)
email_forward	Reenvía un correo a nuevos destinatarios
email_draft_create	Guarda un borrador sin enviar
email_draft_list	Lista todos los borradores

Organización (8)

Herramienta	Descripción
email_move	Mueve un correo a una carpeta diferente. Admite sourceFolder para IMAP/iCloud
email_transfer	Mueve o copia correos entre cuentas, conservando el mensaje original (remitente, fecha, hilo) mediante transferencia MIME sin procesar. deleteAfter=true elimina el origen solo después de una importación confirmada (movimiento seguro entre cuentas)
email_delete	Elimina un correo (papelera o permanente). Admite sourceFolder para IMAP/iCloud
email_mark	Marca como leído/no leído, destacado o marcado. Admite sourceFolder para IMAP/iCloud
email_label	Añadir/eliminar etiquetas (solo Gmail)
email_folder_create	Crea una nueva carpeta
email_get_labels	Lista todas las etiquetas con recuentos (solo Gmail)
email_get_categories	Lista todas las categorías (solo Outlook)

Operaciones por lotes (3)

Herramienta	Descripción
email_batch_delete	Elimina varios correos a la vez (hasta 1000 para Gmail, lotes de 20 para Outlook, rangos UID para IMAP)
email_batch_move	Mueve varios correos a una carpeta en una sola llamada
email_batch_mark	Marca varios correos como leídos/no leídos, destacados o marcados a la vez

Todas las herramientas por lotes aceptan un parámetro sourceFolder para IMAP/iCloud e incluyen un respaldo secuencial para máxima compatibilidad.

Uso con Claude Code

Añade lo siguiente a tu archivo .mcp.json (a nivel de proyecto o global ~/.claude/.mcp.json):

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}

Una vez configurado, puedes pedirle a Claude que interactúe con tu correo:

• "Revisa mi bandeja de entrada en busca de mensajes no leídos"
• "Busca correos de alice@example.com en la última semana"
• "Responde al último correo de Bob y dale las gracias"
• "Mueve todos los boletines a la carpeta Archivo"
• "Elimina todos los correos no deseados" (usa operaciones por lotes para mayor velocidad)
• "Redacta un correo de seguimiento al equipo sobre la reunión"

Desarrollo

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode (watch for changes)
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run integration tests (requires real email accounts)
pnpm test:integration

Soporte

Si este proyecto te resulta útil, considera apoyar su desarrollo:

• GitHub Sponsors
• Buy Me a Coffee

Licencia

MIT