better-email-mcp

Gestión de correo electrónico vía IMAP/SMTP, multi-cuenta

Documentación

Better Email MCP

mcp-name: io.github.n24q02m/better-email-mcp

Correo IMAP/SMTP para agentes de IA: lee, envía, organiza carpetas y gestiona archivos adjuntos en múltiples cuentas, con autodetección.

Proyectos hermanos de n24q02m (clic para expandir)

Proyecto	Eslogan	Etiqueta
agent-chat-plugin	Agentes de IA pares chatean en una carpeta compartida: sin intermediario humano, sin orquestador, fun...	Herramientas
better-code-review-graph	Grafo de conocimiento para revisiones de código eficientes en tokens: búsqueda semántica y llamadas...	MCP
better-drive	Sincronización bidireccional de Google Drive con filtro .driveignore: motor rclone, bandeja de Windows	Herramientas
better-email-mcp	Correo IMAP/SMTP para agentes de IA: lee, envía, organiza carpetas y gestiona archivos adjuntos...	MCP
better-godot-mcp	Servidor MCP compuesto para Godot Engine: 17 herramientas compuestas para desarrollo de juegos asistido...	MCP
better-notion-mcp	Notion centrado en Markdown para agentes de IA: páginas, bases de datos, bloques y comentarios...	MCP
better-semantic-release	Bifurcación directa de python-semantic-release con protecciones de seguridad de lanzamiento integradas (or...	Herramientas
better-telegram-mcp	Telegram para agentes de IA: mensajes, chats, medios y contactos en ambas cuentas...	MCP
better-workspace-mcp	Servidor MCP de Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Mercado de plugins de Claude Code para los servidores MCP de n24q02m: instala búsqueda web...	Marketplace
imagine-mcp	Comprensión y generación de imágenes y vídeos para agentes de IA: en Gemini, Op...	MCP
jules-task-archiver	Extensión de Chrome para operaciones masivas en tareas de Jules mediante la API batchexecute...	Herramientas
mcp-core	Base compartida para crear servidores MCP: transporte Streamable HTTP, OAut...	MCP
mnemo-mcp	Memoria persistente de IA con búsqueda híbrida y sincronización integrada. Abierta, gratuita, ilimit...	MCP
qwen3-embed	Incrustación y reordenación de texto Qwen3 ligera mediante ONNX Runtime y GGUF	Biblioteca
skret	Secretos sin servidor.	CLI
tacet	Una cascada neuro-simbólica autodestilante que amortiza el coste de LLM en el conocim...	Herramientas
web-core	Paquete de infraestructura web compartida para búsqueda, scraping, seguridad HTTP y alm...	Biblioteca
wet-mcp	Servidor MCP de código abierto para agentes de IA: búsqueda web, extracción de contenido y bib...	MCP

Tabla de contenidos

Características
Instalación
CLI
Smithery
Documentación
Herramientas
Comparación
Remoto (modo HTTP)
Código de dispositivo OAuth de Outlook (modo HTTP)
Configuración
Seguridad
Compilar desde el código fuente
Desplegar en Cloudflare
Modelo de confianza
Licencia

Características

Soporte multi-cuenta: gestiona 6 o más cuentas de correo (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, IMAP personalizado)
Contraseñas de aplicación: no requiere configuración OAuth2 para la mayoría de proveedores; clona y ejecuta en 1 minuto
4 herramientas compuestas con 22 acciones (más help + config__open_relay): búsqueda, lectura, envío, respuesta, reenvío, organización y configuración de credenciales en una sola llamada
Autodetección: la configuración del proveedor se detecta a partir de la dirección de correo; se admite host IMAP personalizado
Consciente de hilos: responder/reenviar mantiene las cabeceras In-Reply-To y References
Optimización de tokens por niveles: descripciones comprimidas + herramienta help bajo demanda + Recursos MCP

Instalación

El servidor funciona en dos modos: stdio (predeterminado, un solo usuario, credenciales de variables de entorno) y HTTP (opt-in, multi-usuario con OAuth 2.1). Para stdio, añádelo a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "better-email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-email-mcp@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "user@gmail.com:app-password"
      }
    }
  }
}

Las cuentas múltiples se separan con comas: user1@gmail.com:pass1,user2@outlook.com:pass2. Consulta Configuración para todas las variables de entorno, y Remoto (modo HTTP) para ejecutar un servidor multi-usuario alojado.

La mayoría de proveedores usan una Contraseña de aplicación (sin configuración OAuth); Outlook/Hotmail/Live usan un flujo de código de dispositivo OAuth integrado en modo HTTP. La configuración (host IMAP/SMTP, puerto) se autodetecta a partir del dominio del correo.

CLI

El paquete incluye un único binario, better-email-mcp (se ejecuta mediante npx @n24q02m/better-email-mcp). Sin argumentos, inicia el servidor MCP sobre stdio; también acepta una bandera y un subcomando:

Invocación	Descripción
`better-email-mcp`	Inicia el servidor MCP sobre stdio (predeterminado). Lee las credenciales de `EMAIL_CREDENTIALS`, o de `EMAIL_USER` + `EMAIL_APP_PASSWORD`
`better-email-mcp --http`	Inicia el servidor en modo HTTP (multi-usuario, OAuth 2.1). Equivalente a `MCP_TRANSPORT=http` o `TRANSPORT_MODE=http`
`better-email-mcp auth [outlook] <email> [--client-id=<id>]`	Autentica una cuenta de Outlook/Hotmail/Live mediante el flujo de Código de Dispositivo OAuth2. Los tokens se guardan en `~/.better-email-mcp/tokens.json`. El argumento posicional de proveedor `outlook` es opcional (el correo tiene un único proveedor OAuth2); `--client-id` anula `OUTLOOK_CLIENT_ID` para una aplicación Azure AD autoalojada
`better-email-mcp logout [<email>]`	Borra los tokens de Outlook almacenados localmente. Omite `<email>` para borrar todos los tokens almacenados

# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/better-email-mcp

# HTTP multi-user server
npx @n24q02m/better-email-mcp --http

# One-off Outlook OAuth device-code sign-in
npx @n24q02m/better-email-mcp auth user@outlook.com

# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/better-email-mcp logout user@outlook.com

auth/logout son solo para direcciones de Outlook/Hotmail/Live: otros proveedores usan una Contraseña de aplicación en EMAIL_CREDENTIALS. Consulta Remoto (modo HTTP) para la configuración HTTP.

Smithery

Publicado con una configuración de Smithery (smithery.yaml). Smithery ejecuta el servidor sobre stdio sin necesidad de configuración de compilación; las credenciales se proporcionan en tiempo de ejecución mediante el propio flujo de configuración del servidor (consulta Configuración). El comando de inicio es:

startCommand:
  type: stdio
  commandFunction: |-
    (config) => ({ command: 'npx', args: ['-y', '@n24q02m/better-email-mcp'] })

Documentación

Documentación completa en mcp.n24q02m.com/servers/better-email-mcp/setup/:

Configuración: métodos de instalación para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Resumen de modos: stdio (predeterminado) y HTTP (opt-in, multi-usuario con OAuth 2.1)
Configuración multi-usuario: modelo de credenciales por JWT-sub

Instalar con agente de IA: pega esto en tu agente de codificación de IA:

Instala el servidor MCP better-email-mcp siguiendo los pasos en https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

Herramientas

Renombrado de herramienta pública

La herramienta pública send se sustituye por messages con action: new, reply o forward. Esto sigue el estándar MCP N+2: el envío es una acción del dominio de mensajes, por lo que mantener una entrada separada send duplicaría ese dominio y añadiría superficie redundante de lista de herramientas y temas de ayuda. El nombre antiguo se elimina directamente; no hay alias de compatibilidad.

Nombre público antiguo	Nombre público nuevo	Motivo	Eliminación de alias
`send`	`messages` (`action: new \| reply \| forward`)	Regla de herramienta de dominio N+2: el correo saliente forma parte de la mega-herramienta `messages`, no de una segunda herramienta a nivel de acción.	Eliminado directamente en la versión Unreleased; sin alias

Herramienta	Acciones	Descripción
`messages`	`search`, `read`, `mark_read`, `mark_unread`, `flag`, `unflag`, `move`, `archive`, `trash`, `new`, `reply`, `forward`	Busca, lee, organiza, redacta, responde y reenvía correos
`folders`	`list`, `status`	Lista las carpetas del buzón o lee metadatos IMAP STATUS específicos
`attachments`	`list`, `download`	Lista y descarga archivos adjuntos de correo
`config`	`status`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear`	Configuración de credenciales mediante relevo de navegador, comprobación de estado, restablecimiento, re-resolución, limpieza de caché
`config__open_relay`	-	Abre el formulario de configuración de relevo en el navegador y devuelve la URL de relevo
`help`	-	Obtiene la documentación completa de cualquier herramienta

Recursos MCP

URI	Descripción
`email://docs/messages`	Referencia de operaciones de mensajes
`email://docs/folders`	Referencia de operaciones de carpetas
`email://docs/attachments`	Referencia de operaciones de archivos adjuntos
`email://docs/help`	Documentación completa
`email://docs/config`	Referencia de configuración de credenciales y configuración en tiempo de ejecución

Comparación

Cómo se posiciona better-email-mcp frente a competidores directos en cada pilar:

Capacidad	better-email-mcp	email-mcp	Gmail-MCP-Server	mcp-mail-server
IMAP/SMTP (independiente del proveedor)	Sí	Sí	No (solo API de Gmail)	Sí
Multi-cuenta	Sí (credenciales separadas por comas)	Sí	No (credencial global única)	No (una cuenta por instancia)
Contraseñas de aplicación	Sí (sin configuración OAuth)	Sí	No (solo OAuth2)	Sí
Autodetección a partir de la dirección de correo	Sí	Sí (8 proveedores)	n/d (solo Gmail)	No (host/puerto manuales)
OAuth de Outlook integrado (sin aplicación Azure del usuario)	Sí (código de dispositivo, cliente patrón Thunderbird)	parcial (OAuth2 XOAUTH2, experimental)	No (OAuth de Google proporcionado por el usuario)	No
Archivos adjuntos (listar + descargar)	Sí	Sí	Sí	Sí
Modo HTTP multi-usuario (por JWT-sub)	Sí (OAuth 2.1, autoalojable)	No (solo stdio)	No (solo stdio)	No (solo stdio)

Remoto (modo HTTP)

Ejecuta como servidor HTTP multi-usuario con autenticación OAuth 2.1:

{
  "mcpServers": {
    "better-email": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

Autoalojamiento (modo HTTP)

Modo multi-usuario único (formulario de relevo para proveedores de Contraseña de aplicación + código de dispositivo OAuth de Outlook integrado):

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e PUBLIC_URL=https://your-domain.com \
  n24q02m/better-email-mcp:latest

Los usuarios proporcionan sus propias credenciales de correo mediante el flujo OAuth / formulario de pegado. No se necesita EMAIL_CREDENTIALS en el servidor. Con el autoalojamiento Docker predeterminado, las credenciales por usuario se guardan en un almacén en memoria (se borran al reiniciar); los usuarios las reenvían tras un reinicio. El OAuth de Outlook usa el cliente público de Azure integrado (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, patrón Thunderbird): no se necesita registro de aplicación Azure por parte del usuario.

Modo serverless de Cloudflare (solo KV)

Autoalojable como instancia serverless por usuario en Cloudflare Workers + Containers: cada JWT sub tiene su propio Container Durable Object, y todas las credenciales Y los tokens OAuth de Outlook están cifrados con AES-256-GCM en Workers KV (un blob subs/<sub>/config por usuario) para que sobrevivan al escalado a cero / recreación del contenedor sin reautenticación. La clave de firma JWT se deriva de forma determinista de CREDENTIAL_SECRET (EdDSA), por lo que la identidad del usuario es estable entre recreaciones. Secretos necesarios: CREDENTIAL_SECRET (bóveda por sub + EdDSA), MCP_RELAY_PASSWORD (puerta del formulario), MCP_DCR_SERVER_SECRET (despliegue multi-usuario intencional). Consulta wrangler.jsonc.

Clave de tokens de Outlook por JWT sub (en el blob KV por sub) resuelve la antigua ambigüedad tokens.json clave-por-correo (error conocido n.º 4 de CLAUDE.md): las cuentas de Outlook de dos usuarios ya no pueden colisionar. Advertencia: localhost cuentas IMAP (email:pass:localhost:1993) son válidas para implementaciones locales / en VM pero NO pueden funcionar en Cloudflare — no hay un proxy IMAP co-ubicado dentro del contenedor. Usa un host IMAP accesible públicamente en CF.

Código de dispositivo OAuth de Outlook (modo HTTP)

En modo HTTP, las cuentas de Outlook/Hotmail/Live usan OAuth2 con código de dispositivo automáticamente. En el primer uso:

El servidor imprime un código de dispositivo y una URL de inicio de sesión de Microsoft
Abre la URL en un navegador e introduce el código
Inicia sesión y autoriza la aplicación
Los tokens se persisten por sub de JWT — en el blob de credenciales cifrado de Cloudflare KV (subs/<sub>/config) en la implementación serverless, en el almacén local en memoria para HTTP local, o en ~/.better-email-mcp/tokens.json para un solo usuario / stdio

OAuth usa el cliente público de Azure incluido (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, patrón Thunderbird) — no se necesita registro de Azure por parte del usuario.

En modo stdio, las cuentas de Outlook usan una Contraseña de aplicación (Configuración de la cuenta de Outlook → Seguridad → Opciones de seguridad avanzadas → Contraseñas de aplicación).

Configuración

Para confiar en la configuración de mise automáticamente, establece trusted_config_paths en la configuración a nivel de usuario en ~/.config/mise/config.toml; no lo añadas al .mise.toml de este proyecto.

Variable	Requerida	Predeterminado	Descripción
`EMAIL_CREDENTIALS`	Sí (stdio)	-	Credenciales de correo, `email:app-password` por cuenta, separadas por comas para múltiples cuentas. Host/puerto IMAP personalizado opcional: `email:password:imap_host:imap_port`
`EMAIL_USER`	Alternativa (stdio, cuenta única)	-	Dirección de correo. Se usa con `EMAIL_APP_PASSWORD` como alternativa por campo a `EMAIL_CREDENTIALS`; se fusiona en `EMAIL_CREDENTIALS` al arrancar
`EMAIL_APP_PASSWORD`	Alternativa (stdio, cuenta única)	-	Contraseña de aplicación (Gmail/Yahoo/iCloud) o Contraseña de aplicación de Outlook; se usa con `EMAIL_USER`
`PUBLIC_URL`	No (http)	-	URL pública del servidor para enlaces de relay / redirección OAuth
`PORT`	No	`0` (asignado por el SO)	Puerto del servidor (modo http); establécelo explícitamente (p. ej. `8080`) para vincular un puerto fijo
`HOST`	No	-	Dirección de enlace (modo http)
`MCP_AUTH_DISABLE`	No (http)	-	Establécelo en `1` para omitir la verificación de JWT Bearer cuando hay una puerta de enlace de autenticación externa
`OUTLOOK_CLIENT_ID`	No	`d56f8c71-9f7c-43f4-9934-be29cb6e77b0` (cliente público incluido)	Sobrescribe el cliente público de Azure AD incluido para OAuth2 de Outlook autoalojado (o `--client-id=<id>` en `auth`, que sobrescribe esta variable de entorno)
`OUTLOOK_EMAIL`	No	-	Solución alternativa cuando la respuesta del código de dispositivo de Microsoft omite el campo de correo electrónico
`OUTLOOK_TENANT`	No	`consumers` (stdio/CLI), `common` (código de dispositivo http)	Directorio de Microsoft contra el que iniciar sesión, usado tanto para el código de dispositivo como para el punto final de renovación de tokens. Establece `common` para un buzón de trabajo/escuela (Entra ID), o un GUID de inquilino / dominio verificado para fijar un directorio
`OUTLOOK_SCOPES`	No	`https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access`	Lista de ámbitos separados por espacios. Redúcela (p. ej. elimina `SMTP.Send`) para una implementación de solo lectura — un consentimiento otorgado con menos ámbitos no se puede renovar contra la lista completa
`OUTLOOK_EXTRA_DOMAINS`	No	-	Dominios separados por comas enrutados a OAuth además de `outlook.com`/`hotmail.com`/`live.com`. Necesario para un buzón de Microsoft 365 en tu propio dominio, que de otro modo parece una cuenta de contraseña

Múltiples cuentas

EMAIL_CREDENTIALS=user1@gmail.com:pass1,user2@outlook.com:pass2,user3@yahoo.com:pass3

Host IMAP personalizado

# Custom hostname (default port 993, implicit TLS)
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com

# Custom hostname with a custom port
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com:1993

# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
EMAIL_CREDENTIALS=user@custom.com:password:localhost:1993

Cada cuenta puede usar su propio host y puerto. Un puerto distinto de 993 se trata como texto plano/STARTTLS — la forma habitual para un proxy IMAP local (por ejemplo email-oauth2-proxy).

Cuentas de trabajo/escuela de Microsoft 365

Un buzón en una organización de Microsoft 365 — incluido uno en tu propio dominio — inicia sesión a través de Entra ID en lugar del directorio de consumidores, y Microsoft deshabilitó la autenticación básica para Exchange Online en 2024, por lo que una Contraseña de aplicación no es una opción. Dos ajustes lo hacen funcionar:

# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common                      # or a tenant GUID / verified domain

# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.com

OUTLOOK_TENANT se aplica también a la renovación de tokens, no solo al inicio de sesión inicial — renovar un token de trabajo/escuela contra el directorio de consumidores falla con AADSTS7000012: The grant was obtained for a different tenant.

Si el buzón fue consentido con un consentimiento más restringido (digamos IMAP pero no SMTP), hazlo coincidir con OUTLOOK_SCOPES para que la renovación no solicite más de lo que fue otorgado.

Lenguaje de consulta de búsqueda

Consulta	Descripción
`UNREAD`	Correos no leídos
`FLAGGED`	Correos destacados
`SINCE 2024-01-01`	Correos después de una fecha
`FROM boss@company.com`	Correos de un remitente
`SUBJECT meeting`	Correos que coinciden con el asunto
`UNREAD SINCE 2024-06-01`	Filtro compuesto

Proveedores compatibles

Proveedor	Autenticación	Guardar en enviados
Gmail	Contraseña de aplicación	Automático (omitido)
Yahoo	Contraseña de aplicación	Automático (omitido)
iCloud/Me.com	Contraseña específica de la aplicación	Automático (omitido)
Outlook/Hotmail/Live	OAuth2 (Código de dispositivo)	IMAP APPEND
Zoho	Contraseña de aplicación	IMAP APPEND
ProtonMail	ProtonMail Bridge	IMAP APPEND
Personalizado	Vía `email:pass:imap.host`	IMAP APPEND

Seguridad

Saneamiento de credenciales — Las contraseñas nunca se filtran en mensajes de error
Contraseñas de aplicación — Usa contraseñas específicas de la aplicación, no contraseñas normales
Almacenamiento de tokens — Los tokens OAuth de Outlook se guardan con permisos 600
Validación IMAP — Las consultas de búsqueda se validan antes de ejecutarse

Compilar desde el código fuente

git clone https://github.com/n24q02m/better-email-mcp.git
cd better-email-mcp
bun install
bun run dev

Implementar en Cloudflare

Ejecuta tu propia instancia multiusuario de better-email sin servidor en Cloudflare (Containers + KV). Cada sub de JWT obtiene su propio Container Durable Object, y las credenciales de correo de cada usuario y los tokens OAuth de Outlook se cifran con AES-256-GCM en un único blob de Workers KV por usuario, por lo que sobreviven al escalado a cero / recreación del contenedor sin necesidad de reautenticación.

Requisitos previos: una cuenta de Cloudflare en el plan de pago Workers — necesario para Containers (el nivel gratuito de Cloudflare no incluye Containers) — y la CLI wrangler.

git clone https://github.com/n24q02m/better-email-mcp && cd better-email-mcp
wrangler login
Crea el espacio de nombres KV (better-email es solo KV — sin D1 / Vectorize):
```
wrangler kv namespace create better-email-kv
```
Pega el id devuelto en <better-email-kv-namespace-id> en wrangler.jsonc.

Sube la imagen del contenedor a tu registro gestionado de Cloudflare (CF Containers no puede extraer de registros externos directamente), luego establece <YOUR_ACCOUNT_ID> en wrangler.jsonc:

docker pull ghcr.io/n24q02m/better-email-mcp:beta
docker tag ghcr.io/n24q02m/better-email-mcp:beta better-email-mcp:beta
wrangler containers push better-email-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/better-email-mcp:beta

Apunta wrangler.jsonc a tu propio dominio: establece <YOUR_PUBLIC_URL> (p. ej. https://email.example.com) y <YOUR_WORKER_DOMAIN> (p. ej. email.example.com).
Establece los secretos de implementación:
```
wrangler secret put CREDENTIAL_SECRET      # per-sub vault key + deterministic EdDSA signing (required)
wrangler secret put MCP_RELAY_PASSWORD     # gate for the /authorize setup form
wrangler secret put MCP_DCR_SERVER_SECRET  # proof of an intentional multi-user deploy
```
Sobrescrituras opcionales de Outlook — solo para reemplazar el cliente de código de dispositivo público de Azure incluido (el predeterminado no necesita una aplicación de Azure por parte del usuario): wrangler secret put OUTLOOK_CLIENT_ID y wrangler secret put OUTLOOK_EMAIL. Para una organización de Microsoft 365, también establece OUTLOOK_TENANT (y OUTLOOK_EXTRA_DOMAINS para buzones en tu propio dominio).
wrangler deploy, luego abre <YOUR_PUBLIC_URL>/authorize y completa el formulario de relay del navegador.

Los usuarios finales proporcionan sus propias credenciales de correo — una Contraseña de aplicación mediante el formulario de pegado, o el inicio de sesión de código de dispositivo de Outlook incluido — a través de ese formulario de relay; no hay EMAIL_CREDENTIALS del lado del servidor. El almacenamiento se asigna a Cloudflare vía MCP_STORAGE_BACKEND=cf-kv (ya establecido en wrangler.jsonc); consulta modo serverless de Cloudflare (solo KV) para los detalles de cifrado y confianza.

Modelo de confianza

Este plugin implementa TC-NearZK. La durabilidad del almacenamiento depende del modo de implementación; consulta el modelo de confianza de mcp-core para la clasificación completa.

Modo	Almacenamiento	Cifrado	¿Quién puede leer tus datos?
HTTP remoto (Cloudflare)	Workers KV cifrado `subs/<sub>/config`	AES-256-GCM	Operador del servidor (admin = usuario)
HTTP local Docker	En memoria `Map<sub, CredentialPayload>`	Solo en proceso	Proceso del servidor (se borra al reiniciar)
stdio	directorio de configuración de platformdirs `mcp` (`config.enc`; p. ej. `%APPDATA%\mcp\Config\config.enc` en Windows)	AES-GCM, clave vinculada a la máquina	Solo tu usuario del SO (permiso de archivo 0600)

Licencia

Apache-2.0 — Consulta LICENSE.