Email MCP for Gmail, iCloud and microsoft

Organiza, marca, lee, elimina y limpia el correo electrónico con IA.

GitHub
22
Prueba este MCPPatrocinado

Documentación

@marlinjai/email-mcp

email-mcp logo

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) e 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, con respaldo a IMAP para compatibilidad universal

Instalación

Instalar globalmente desde npm:

npm install -g @marlinjai/email-mcp

O ejecutar directamente con npx (sin necesidad de instalar):

npx @marlinjai/email-mcp

Inicio Rápido

  1. Ejecuta el asistente de configuración interactivo para añadir tus cuentas de correo:
npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

La bandera -p/--package es obligatoria. Este paquete declara dos binarios (email-mcp para el servidor MCP, email-mcp-setup para este asistente). Sin -p, npx ejecuta el binario que coincide con el nombre del propio paquete (email-mcp, el servidor) y pasa silenciosamente email-mcp-setup como un argumento ignorado — el servidor entonces se queda esperando entrada de protocolo MCP en stdin para siempre, sin producir ninguna salida. Parece exactamente un cuelgue. -p le dice a npx explícitamente qué paquete resolver y cuál de sus binarios ejecutar realmente.

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 — así puedes configurar Gmail, Outlook e iCloud de una sola vez.

  1. Añade el servidor a tu configuración de MCP (.mcp.json):
{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}
  1. Empieza 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 por Proveedor

Gmail

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

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Gmail" when prompted
# Choose "Full" or "Restricted" permission scope when asked
# A browser window opens for Google authorization
# Grant the requested permissions and return to the terminal

El asistente pregunta qué alcance de permisos de Gmail autorizar:

  • Completo (predeterminado) — todo lo siguiente, más la eliminación permanente inmediata que omite la Papelera (https://mail.google.com/, el alcance de máximo permiso de Gmail).
  • Restringido — leer, enviar, etiquetar, archivar y mover a la Papelera (gmail.modify + gmail.settings.basic), pero sin eliminación permanente. Cada herramienta de este servidor funciona idénticamente bajo Restringido excepto una eliminación explícita de permanent: true, que falla con un error de la API de Gmail en lugar de tener éxito.

Pasa --scope full o --scope restricted para omitir la pregunta, o establece EMAIL_MCP_GMAIL_SCOPE=restricted en el entorno donde se ejecuta el asistente.

Nota: Si prefieres usar tu propia aplicación OAuth en lugar de la compartida que incluye este paquete, crea un Cliente OAuth 2.0 de Escritorio en la Consola de Google Cloud con la API de Gmail habilitada, luego establece EMAIL_MCP_GMAIL_CLIENT_ID y EMAIL_MCP_GMAIL_CLIENT_SECRET en el entorno antes de ejecutar el asistente de configuración (y en el entorno del servidor MCP, ya que la re-autenticación usa las mismas variables). Esto te da tu propio ciclo de vida de tokens, independiente del proyecto Cloud del editor, y evita la advertencia de aplicación no verificada de Google y el límite de 100 usuarios de prueba para tus propias cuentas una vez que te añadas como usuario de prueba en tu propia aplicación.

Outlook

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

npx -y -p @marlinjai/email-mcp@latest 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, registra una en el Portal de Azure con permisos Mail.ReadWrite, Mail.Send, MailboxSettings.ReadWrite (necesario para email_create_block_rule) y offline_access, luego establece EMAIL_MCP_OUTLOOK_CLIENT_ID en el entorno antes de ejecutar el asistente de configuración.

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 -y -p @marlinjai/email-mcp@latest 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 -y -p @marlinjai/email-mcp@latest 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 (32)

Gestión de Cuentas (4)

HerramientaDescripción
email_list_accountsLista todas las cuentas configuradas con estado de conexión
email_add_accountAñade una nueva cuenta IMAP o iCloud (Gmail/Outlook requieren el asistente de configuración)
email_remove_accountElimina una cuenta y sus credenciales almacenadas; revoca la concesión de Google para Gmail, elimina los tokens de Outlook de la caché local de tokens e informa el resultado
email_test_accountPrueba la conexión a una cuenta

Lectura y Búsqueda (6)

HerramientaDescripción
email_list_foldersLista todas las carpetas/etiquetas de una cuenta
email_searchBusca correos con filtros. Devuelve resultados compactos por defecto (returnBody=false). Establece returnBody=true para incluir cuerpos completos de correo
email_getObtiene el contenido completo de un correo por ID (cabeceras, cuerpo, metadatos de adjuntos)
email_get_threadObtiene un hilo/conversación de correo completo
email_get_attachmentDescarga un adjunto específico por ID (devuelve datos en base64)
email_save_attachmentDescarga un adjunto directamente al disco, devolviendo solo metadatos — evita el costo de tokens de transferir archivos grandes como base64. outputPath es relativo a un directorio fijo de descargas (~/.email-mcp/downloads, sobrescribible con EMAIL_MCP_DOWNLOADS_DIR) y no puede escapar de él

Envío y Borradores (6)

HerramientaDescripción
email_sendRedacta y envía un nuevo correo (para, cc, cco, asunto, cuerpo)
email_replyResponde a un correo (soporta responder a todos, preserva el hilo)
email_forwardReenvía un correo a nuevos destinatarios
email_draft_createGuarda un borrador sin enviar
email_draft_updateActualiza un borrador existente en su lugar. En Gmail/Outlook el id del borrador no cambia; en iCloud/IMAP genérico no hay actualización en su lugar (los mensajes IMAP son inmutables), así que el borrador antiguo se elimina y se añade uno nuevo — el id devuelto es un id nuevo, úsalo siempre en adelante
email_draft_listLista todos los borradores

Organización (8)

HerramientaDescripción
email_moveMueve un correo a una carpeta diferente. Soporta sourceFolder para IMAP/iCloud
email_transferMueve o copia correos entre cuentas, preservando el mensaje original (remitente, fecha, hilo) mediante transferencia MIME cruda. deleteAfter=true envía a la Papelera el origen solo después de una importación confirmada (movimiento seguro entre cuentas)
email_deleteElimina un correo (Papelera o permanente). Soporta sourceFolder para IMAP/iCloud
email_markMarca como leído/no leído, destacado o con bandera. Soporta sourceFolder para IMAP/iCloud
email_labelAñade/elimina etiquetas (solo Gmail)
email_folder_createCrea una nueva carpeta
email_get_labelsLista todas las etiquetas con conteos (solo Gmail)
email_get_categoriesLista todas las categorías (solo Outlook)

Operaciones por Lotes (3)

HerramientaDescripción
email_batch_deleteElimina múltiples correos a la vez (hasta 1000 para Gmail, lotes de 20 para Outlook, rangos UID para IMAP)
email_batch_moveMueve múltiples correos a una carpeta en una sola llamada
email_batch_markMarca múltiples correos como leído/no leído, destacado o con bandera 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.

Moderación de Spam (5)

HerramientaDescripción
email_report_spamReporta un correo como spam/no deseado, entrenando el filtro del propio proveedor — la misma señal que envía el botón "Reportar no deseado" en Gmail/Outlook. Esto es diferente de email_delete, que elimina el mensaje pero no enseña nada al filtro. No es un reporte de abuso al equipo de seguridad del proveedor; solo entrena el filtro de esta cuenta
email_batch_report_spamReporta múltiples correos como spam/no deseado a la vez
email_create_block_ruleCrea una regla permanente que intercepta correos futuros que coincidan con un patrón (dominio/dirección del remitente, asunto o contenido arbitrario de cabecera) y los elimina o los mueve. Usa headerContains (por ejemplo, un dominio Reply-To) para bloquear una familia de plantillas de spam cuyo dominio "De" visible rota — coincidir con el dominio rotatorio directamente deja de funcionar en días. No soportado en iCloud/IMAP genérico (no existe un mecanismo estándar de reglas del lado del servidor entre servidores IMAP). En Outlook, moveToJunk archiva directamente en la carpeta Correo no deseado y requiere el alcance MailboxSettings.ReadWrite. En Gmail, moveToJunk omite la bandeja de entrada (archiva) en lugar de archivar literalmente en Spam — la API de filtros de Gmail rechaza la etiqueta SPAM en reglas permanentes (solo el clasificador propio de Gmail puede aplicarla; email_report_spam aún puede, ya que es una acción directa por mensaje, no un filtro) — y requiere el alcance gmail.settings.basic. Las cuentas autenticadas antes de que existieran estos alcances necesitan volver a ejecutar el asistente de configuración una vez para re-consentir
email_list_block_rulesLista las reglas de bloqueo permanentes de una cuenta, para auditoría o antes de eliminar una
email_delete_block_ruleElimina una regla de bloqueo permanente — úsala para deshacer una regla que resultó demasiado amplia

Solo Gmail y Outlook para las herramientas de reglas; email_report_spam/email_batch_report_spam funcionan en todos los proveedores (iCloud/IMAP recurren a un movimiento de mejor esfuerzo a la carpeta de tipo No deseado de la cuenta, sin señal de entrenamiento ML del proveedor ya que el IMAP genérico no tiene ninguna para entrenar).

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 por mensajes no leídos"
  • "Busca correos de alice@example.com en la última semana"
  • "Responde al último correo de Bob y agradécele"
  • "Mueve todos los boletines a la carpeta Archivo"
  • "Elimina todos los correos de spam" (usa operaciones por lotes para 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

Almacenamiento de Credenciales

Las credenciales de las cuentas están cifradas en reposo con AES-256-GCM en ~/.email-mcp/credentials.enc.

Por defecto, la clave de cifrado se deriva de un identificador estable específico de la máquina (el UUID de hardware en macOS, /etc/machine-id en Linux, o el MachineGuid en Windows), con respaldo al nombre de host cuando no hay ninguno disponible.

Establece la variable de entorno EMAIL_MCP_KEY para proporcionar tu propia frase de contraseña en su lugar. Esto se recomienda cuando el identificador de la máquina puede cambiar (por ejemplo, en contenedores o CI), o cuando quieras mover credentials.enc entre máquinas:

export EMAIL_MCP_KEY="your-strong-passphrase"

Cuando EMAIL_MCP_KEY está establecido, los archivos de credenciales existentes se re-cifran transparentemente con la frase de contraseña la próxima vez que se lean.

El token de actualización de Outlook vive en la caché de tokens de la biblioteca de autenticación de Microsoft (MSAL), ~/.email-mcp/msal-cache.enc, cifrado con el mismo esquema y derivación de clave que credentials.enc, así que EMAIL_MCP_KEY protege ambos archivos. Las versiones anteriores a 1.8.0 mantenían esta caché como JSON plano en ~/.email-mcp/msal-cache.json; 1.8.0 la cifra y elimina el archivo plano la primera vez que lo lee, sin cerrar tu sesión. Volver a una versión anterior después significa iniciar sesión en Outlook de nuevo.

En macOS y Linux, los adjuntos guardados con email_save_attachment se escriben solo para el propietario (0600), y las carpetas que email-mcp crea para ellos son 0700. No están cifrados.

La devolución de llamada de inicio de sesión OAuth iniciada por email-mcp-setup escucha solo en las direcciones de bucle local (127.0.0.1, y ::1 cuando está disponible), así que nada más en tu red puede alcanzarla.

Soporte

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

Licencia

MIT