mail-mcp

La mayoría de los servidores MCP de correo electrónico solo leen desde IMAP. mail-mcp lo hace todo: 30 herramientas para leer, buscar, enviar, responder, reenviar y operaciones masivas a través de IMAP, SMTP, Microsoft Graph API y Exchange Web Services. Multi-cuenta, OAuth2 nativo, construido en Rust. Funciona con Gmail, Microsoft 365, Hotmail/Outlook.com, Zoho y cualquier servidor IMAP/SMTP estándar.

GitHub

Prueba este MCPPatrocinado

Documentación

mail-mcp

Servidor MCP de correo listo para producción para agentes de IA
IMAP + SMTP + EWS + Microsoft Graph API — construido en Rust

La mayoría de los servidores MCP de correo solo hacen lecturas IMAP. Este hace todo: leer, buscar, enviar, responder, reenviar, operaciones masivas, Microsoft Graph API y Exchange Web Services — con OAuth2 real, soporte multi-cuenta y multi-proveedor. Escrito en Rust por velocidad y seguridad.

Novedades en v0.4.13

effective_from() helper + FROM_EMAIL validación de inicio por @arwack en #29 — el seguimiento de su #19. El respaldo from_email → user ahora vive en un solo lugar (SmtpAccountConfig::effective_from()), y MAIL_SMTP_<ID>_FROM_EMAIL se valida cuando el servidor arranca en lugar de fallar en el primer envío.
Cambio de comportamiento — lea antes de actualizar: un FROM_EMAIL malformado (múltiples @, espacios en blanco, parte local vacía o un dominio sin punto) ahora impide que el servidor arranque, para todas las cuentas. Tenga en cuenta que los dominios sin punto como user@localhost o alerts@intranet también se rechazan actualmente; si usa una dirección de relay interno así, retenga la actualización — un seguimiento que relaje la regla del punto está en discusión en #29.
Pruebas de formato de cable APPEND endurecidas por @tordable en #28: el entrecomillado del buzón, la longitud literal anunciada y la carga útil byte a byte ahora se verifican en cada prueba de append.

Novedades en v0.4.12

Lanzamiento comunitario — ambos cambios vinieron de contribuyentes externos. ¡Gracias!

Alias de buzones de iCloud + las lecturas ya no marcan mensajes como leídos por @felipefdl en #16. Los nombres cortos de buzón ahora resuelven a la carpeta real de cada proveedor (Sent → Sent Messages en iCloud / [Gmail]/Sent Mail en Gmail, Trash → Deleted Messages, y así sucesivamente, multi-idioma) en búsqueda, copia y movimiento. Las recuperaciones de mensajes crudos ahora usan BODY.PEEK[], por lo que leer un mensaje a través del MCP ya no establece \Seen como efecto secundario — con un respaldo BODY[] para servidores que rechazan PEEK (el elemento RFC822 obsoleto, eliminado en #23, permanece fuera). Validado contra un buzón real de iCloud por el autor; incluye pruebas de resolución de alias y documentación de configuración de iCloud.
Dockerfile multi-etapa optimizado + docker-compose por @monssefbaakka en #5. Caché de capas cargo-chef, compilaciones cruzadas musl conscientes de TARGETARCH (amd64/arm64) e imagen de runtime scratch — 16.9 MB, desde 25.5 MB — verificada para responder a MCP initialize/tools-list sobre stdio. El pin de toolchain se elevó a Rust 1.90 (las let-chains del código requieren >= 1.88).

Novedades en v0.4.11

Lanzamiento comunitario de corrección de errores — ambas correcciones vinieron de contribuyentes externos. ¡Gracias!

Corregido: guardar en Enviados fallaba silenciosamente en servidores IMAP estrictos (iCloud y otros) por @dominikknafelj en #26, reportado en #25. El flag \Seen introducido en v0.4.10 se enviaba sin la sintaxis de lista de flags entre paréntesis de RFC 3501 (APPEND "Sent" \Seen … en lugar de APPEND "Sent" (\Seen) …), porque async-imap interpola el argumento de flags textualmente. Los servidores estrictos rechazaban el APPEND y la copia enviada se perdía — mientras la herramienta aún reportaba status: ok. Los flags ahora se normalizan antes de llegar al cable, y las respuestas smtp_send_message / smtp_reply_message / smtp_forward_message incluyen un nuevo campo saved_to_sent (true/false, o null cuando guardar está deshabilitado) para que los llamadores puedan detectar fallos de archivado. @tordable diagnosticó y corrigió la misma causa raíz concurrentemente en #24.
Corregido: las lecturas de mensajes devolvían vacío en iCloud por @tdabasinskas en #23. Las recuperaciones de mensajes crudos usaban el elemento RFC822 obsoleto, que iCloud acepta pero deja sin poblar. Las recuperaciones ahora usan el elemento IMAP4rev1 BODY[] — mismas semánticas \Seen, funciona en todas partes — con una prueba de regresión de servidor simulado fijando el formato de cable.

Novedades en v0.4.10

Lanzamiento comunitario — los tres cambios vinieron de contribuyentes externos. ¡Gracias!

Compatibilidad IMAP con NetEase (126.com / 163.com / yeah.net) por @pep-27 en #21. Los servidores de NetEase rechazan el acceso al buzón de clientes que no se identifican. mail-mcp ahora envía el comando ID de RFC 2971 después de la autenticación siempre que el servidor anuncie la capacidad ID. Incluye pruebas de regresión de servidor simulado y documentación de configuración de NetEase en docs/account-setup.md.
MAIL_SMTP_<ID>_FROM_EMAIL — anulación de dirección de remitente por @arwack en #19. Para buzones compartidos/grupales donde SMTP autentica con una cuenta personal pero la dirección De debe ser la dirección del grupo. Se aplica a enviar, responder (incluyendo detección de dirección propia en responder a todos) y reenviar; cae a _USER cuando no está configurado.
Las copias de correo enviado ahora se marcan como \Seen por @ray-of-darkness en #9. Las copias que el MCP agrega a la carpeta Enviados después del envío SMTP ya no aparecen como no leídas.

Novedades en v0.4.9

Nueva herramienta imap_get_attachment — descargar un adjunto individual al disco. Hasta ahora las únicas formas de acceder a los bytes de adjuntos eran imap_get_message (que devuelve metadatos de adjuntos y texto PDF extraído opcional, nunca el binario) y imap_get_message_raw (limitado a 1 MB y codificado en base64 en la respuesta). Un correo de 7 MB con imágenes de rayos X no se podía recuperar en absoluto — sobre el límite, y volcarlo en la respuesta habría reventado el contexto del modelo de todos modos.
Cómo funciona: llame a imap_get_attachment con el message_id más un selector — ya sea part_id (el valor que imap_get_message reporta para cada adjunto) o filename. El servidor recupera el mensaje completo (sin límite de tamaño en el lado del servidor), extrae y decodifica solo esa parte, y lo escribe en disco, devolviendo { file_path, filename, content_type, part_id, size_bytes }. El binario nunca entra en la respuesta, por lo que el contexto se mantiene pequeño. La ruta guardada alimenta directamente a un lector local (por ejemplo, una herramienta de descripción de imágenes o un lector de PDF).
Dónde aterrizan los archivos: argumento output_dir si se da, si no la variable de entorno MAIL_ATTACHMENT_DOWNLOAD_DIR, si no el directorio temporal del sistema. Los nombres de archivo se sanean (solo nombre base, caracteres de control eliminados) para prevenir el path traversal, y se prefijan con el UID del mensaje y el id de la parte para evitar colisiones.
Base64 en línea opcional: configure include_base64: true para también obtener los bytes en la respuesta, pero solo cuando el adjunto tenga como máximo max_inline_bytes (por defecto 256 KiB). Desactivado por defecto.

Novedades en v0.4.8

SAVE_SENT ahora es por cuenta con un valor predeterminado consciente del proveedor. Anteriormente, guardar una copia del correo saliente en la carpeta Enviados vía IMAP APPEND estaba controlado por un único flag global, MAIL_SMTP_SAVE_SENT. El problema: los proveedores que ya guardan el correo enviado en el servidor (Gmail, Zoho) terminaban con dos copias idénticas en Enviados, mientras que un servidor SMTP genérico u Office 365 (que no guardan automáticamente en el envío SMTP) perdían la copia por completo cuando el flag era false.
Valor predeterminado consciente del proveedor (cuando no se configura nada):
- Gmail (smtp.gmail.com): guarda en el servidor y deduplica por Message-ID → el MCP no agrega (false).
- Zoho (smtp.zoho.com): guarda en el servidor pero no deduplica → el MCP no agrega (false), evitando el duplicado.
- Office 365 / SMTP genérico: no guardan automáticamente en el envío SMTP → el MCP sí agrega (true), o la copia enviada se perdería.
Anulación por cuenta: MAIL_SMTP_<ID>_SAVE_SENT=true|false tiene prioridad sobre todo. El global MAIL_SMTP_SAVE_SENT aún funciona como anulación gruesa (gana sobre el valor predeterminado del proveedor, pierde ante la anulación por cuenta).
Precedencia: por cuenta → global → valor predeterminado consciente del proveedor.

Proveedor	Guarda automáticamente en servidor	Valor predeterminado del MCP
Gmail	Sí (con dedupe)	`false`
Zoho	Sí (sin dedupe)	`false`
Office 365 (SMTP)	No	`true`
SMTP genérico / relays	No	`true`

Novedades en v0.4.7

Corrección crítica — graph_send_message descartaba silenciosamente adjuntos en respuestas en hilo. Cuando se llamaba con in_reply_to + attachments, el flujo createReply → PATCH → send incluía los adjuntos en el PATCH contra /me/messages/{id}. Microsoft Graph trata Message.attachments como una propiedad de navegación y descarta silenciosamente el campo en PATCH (respuesta 2xx, sin error), por lo que el mensaje salía como text/html de una sola parte sin archivo. El MCP devolvía status: ok y el llamador asumía éxito. Pérdida de datos invisible.
La corrección: en send_via_reply(), los adjuntos ahora se suben uno a uno a POST /me/messages/{draft_id}/attachments entre el PATCH y el envío. Archivos < 3 MB van en línea (JSON con contentBytes base64); archivos ≥ 3 MB usan createUploadSession con PUTs fragmentados de 4 MB. El campo attachments se eliminó de la estructura PatchDraftRequest para que la regresión no pueda reintroducirse con una edición de tipo correcto.
Sin cambios en los flujos que ya funcionaban. send_via_sendmail (mensajes nuevos sin in_reply_to) usa POST /me/sendMail con attachments en línea en el JSON — Graph SÍ acepta el campo en ese endpoint y nunca lo descartó. Esa ruta no se toca.
Prueba de regresión añadida: patch_draft_request_never_serializes_attachments falla si alguien vuelve a añadir el campo a la estructura.
Referencia: BUG_GRAPH_ATTACHMENTS.md en la raíz del repositorio documenta la reproducción completa, la causa raíz y la evidencia empírica detrás de la corrección.

Novedades en v0.4.6

Aplicación en el servidor de la REGLA DURA #1. Tres versiones de endurecimiento solo por prompt (v0.4.3 → v0.4.4 → v0.4.5) aún dejaban que los LLM ocasionalmente filtraran marcado literal </body_text><parameter name="body_html"> en la bandeja de entrada del destinatario. v0.4.6 añade un validador real que rechaza la llamada a la herramienta antes de cualquier intento SMTP / Graph / EWS si body_text o body_html contiene sintaxis de envoltura de llamada a herramienta. La verificación está conectada en las 5 rutas de envío (smtp_send_message, smtp_reply_message, smtp_forward_message, graph_send_message, ews_send_message).
Los marcadores prohibidos son insensibles a mayúsculas y están estrictamente limitados — solo las pseudo-etiquetas que no tienen uso legítimo en correspondencia humana: <body_text>, </body_text>, <body_html>, </body_html>, <function_calls>, </function_calls>, <invoke name=, </invoke>, y <parameter name="body_*">. Contenido técnico genérico que menciona <parameter> para un esquema XML o <invoke> en un ejemplo de código aún pasa.
Redacción de la REGLA DURA #1 actualizada para anunciar el rechazo en el servidor, para que el LLM sepa que es un contrato duro — no una sugerencia que puede ignorar.
Sin cambios disruptivos para llamadores limpios: los mensajes bien comportados se envían exactamente como antes.

Novedades en v0.4.5

serverInfo ahora informa name="mail-mcp" + el crate version (el framework anteriormente devolvía su propio rmcp 0.16.0, que nunca cambia entre versiones). Útil para verificar la versión activa con /mcp, y así cualquier caché del lado del cliente clave por (servidor, versión) se invalida en cada actualización.
Instrucciones de MCP reorganizadas: las 3 reglas críticas anti-concatenación (que en v0.4.3 y v0.4.4 estaban al final del bloque y podían perderse por truncamiento / atención diluida) ahora aparecen como REGLA ESTRICTA #1, #2, #3 al INICIO, justo después del título. Consolidado en 3 párrafos cortos (anteriormente 3 secciones largas, ~1500 caracteres combinados).
Sin cambios funcionales en el servidor. Mismo SMTP/IMAP/EWS/Graph, mismo conjunto de herramientas, mismo comportamiento. Solo cambió el texto expuesto al cliente.

Importante para que estas reglas surtan efecto

Los clientes que reanudan una sesión con claude --continue (o /resume) NO actualizan el system_prompt de MCP — conservan el de el primer handshake de esa sesión. Si tu sesión es anterior a v0.4.5, las reglas no llegarán a tu contexto incluso si el binario en disco está actualizado. Para recibirlas, inicia una NUEVA sesión en el proyecto (no --continue).

Novedades en v0.4.4

Regla de higiene de vista previa en instructions de MCP: cuando el LLM muestra al usuario la vista previa del correo antes de enviarlo, debe renderizar UNA versión limpia del cuerpo (viñetas estilo markdown, negritas, enlaces como texto + URL) y declarar que el mensaje irá multiparte — pero NO debe volcar el código HTML crudo (<p>, <strong>, <a href>...) en la vista previa. Dos razones:
1. El revisor humano quiere leer el mensaje, no auditar el marcado — mostrar el HTML es ruido.
2. Exhibir tanto la cadena de texto plano COMO la cadena HTML lado a lado en la vista previa es exactamente el contexto que históricamente ha llevado a los LLM a concatenarlas en la eventual llamada de herramienta (el error documentado en v0.4.3). Ocultar el código HTML de la vista previa elimina la tentación.
Complementa la regla LA VISTA PREVIA NO ES IGUAL A LA LLAMADA DE HERRAMIENTA introducida en v0.4.3.

Novedades en v0.4.3

Guía del lado del servidor contra llamadas de herramienta malformadas. El bloque instructions de MCP ahora dice explícitamente al LLM llamante que body_text y body_html son DOS CAMPOS JSON SEPARADOS y deben NUNCA concatenarse. La redacción anterior ("enviar AMBOS body_text Y body_html") era ambigua y algunos LLM la interpretaron como "concatenar ambos con pseudo-etiquetas <body_text>...</body_html> dentro de una sola cadena body_text". Cuando eso ocurre, el destinatario ve contenido duplicado distorsionado, Y cualquier sesión posterior de Claude que abra la copia guardada a través de este MCP recibe un bloqueo de Política de Uso (el <invoke>...</invoke> filtrado parece un intento de inyección de prompt a los filtros de seguridad). La nueva instrucción muestra un ejemplo CORRECTO vs INCORRECTO y prohíbe pseudo-etiquetas / sintaxis de envoltura de llamada de herramienta dentro de los campos de correo.

Novedades en v0.4.2

Pipeline de lanzamiento corregido: el trabajo publish-npm en el flujo de trabajo de lanzamiento de CI ha sido deshabilitado. Fue heredado del fork upstream y intentaba publicar en @bradsjm/mail-imap-mcp-rs, un ámbito que esta organización no posee — cada lanzamiento fallaba con 404 en ese paso. Consulta "Lanzamiento" a continuación para la explicación completa y cómo re-habilitar la publicación npm si es necesario.
Lanzamientos auto-disparados al empujar etiquetas: .github/workflows/release.yml ahora se activa en push: tags: ['v*'], así que etiquetar vX.Y.Z y empujar es todo lo que se necesita para cortar un lanzamiento. workflow_dispatch se conserva como una vía de escape manual.
Limpieza: se eliminó el flujo de trabajo init-npm-placeholder.yml colgante (también referenciaba el ámbito npm del fork).
docs: el README gana una sección "Lanzamiento" que documenta el nuevo flujo y la decisión sobre npm.

Novedades en v0.4.1

Corrección: save_to_sent_folder ahora archiva los bytes RFC822 exactos que fueron enviados (vía lettre.formatted()), en lugar de un stub de solo texto hecho a mano. La copia en la carpeta de Enviados conserva el cuerpo HTML, la estructura multipart/alternative y el asunto codificado RFC 2047 — sin más ??? donde solían estar los acentos, y el HTML ya no se descarta silenciosamente.
Mejora: detección localizada de la carpeta de Enviados — Enviado[s], Elementos enviados, Enviadas, Itens enviados, Envoyés, Éléments envoyés, Gesendet, Posta inviata, Verzonden, Wysłane, más variantes anidadas. Anteriormente solo se reconocían nombres en inglés, por lo que las cuentas IMAP de Zoho/localizadas caían en una carpeta "Sent" inexistente.
Mejora: smtp_forward_message acepta body_html (antes estaba codificado a solo texto plano).
Mejora: el envío EWS gana bcc, in_reply_to, references (vía <t:InternetMessageHeaders>), más validación completa de destinatarios + longitud de asunto — ahora a la par con las rutas de envío SMTP y Graph.
Mejora: los respaldos de hilos de la API Graph ahora registran. WARN cuando la llamada HTTP de búsqueda de mensajes falla (límite de tasa, 5xx, permisos) para que los operadores vean hilos degradados debido a un error real; DEBUG cuando el mensaje original legítimamente no se encuentra.
Refactor: el análisis XML de EWS migró de coincidencia de subcadenas a quick-xml. Corrige un error latente de colisión de espacios de nombres (<soap:Body> vs <t:Body>), decodifica correctamente entidades XML y CDATA, y maneja valores de atributos que contienen = (común en IDs de elementos EWS tipo base64).
Limpieza: cero advertencias en cargo build --release.
Pruebas: 64 (desde 47).

Por Qué Este Proyecto

	mail-mcp	MCP de correo típico
Lectura/escritura IMAP	18 herramientas	3-5 herramientas
Envío/respuesta/reenvío SMTP	Sí	No o roto
API Graph de Microsoft	Sí	No
EWS (Exchange Web Services)	Sí	No
OAuth2 (XOAUTH2)	Nativo	No
Multi-cuenta	Sí	Cuenta única
Microsoft 365 + Hotmail	Ambos funcionan	Generalmente ninguno
Lenguaje	Rust (rápido, seguro)	TypeScript/Python
Pruebas	64 unitarias + integración	Solo mocks
Advertencias en compilación de lanzamiento	0	Varía

Matriz de Características

Proveedor	IMAP	SMTP	API Graph	EWS	OAuth2	Multi-cuenta
Microsoft 365 (empresa)	Sí	Dependiente del administrador	Sí	Sí	Sí	Sí
Hotmail / Outlook.com	Sí	Bloqueado por MS	Sí	Sí	Sí	Sí
Gmail	Sí	Sí	—	—	Sí	Sí
Apple iCloud	Sí	Sí	—	—	—	Sí
Zoho	Sí	Sí	—	—	—	Sí
Fastmail	Sí	Sí	—	—	—	Sí
Cualquier servidor IMAP/SMTP	Sí	Sí	—	—	—	Sí

EWS es la forma más simple de agregar cuentas de Microsoft — un solo token OAuth2 para leer y enviar. Funciona incluso en inquilinos que bloquean la API Graph e IMAP.

Inicio Rápido — Deja que Claude Code lo haga

Copia y pega este prompt en Claude Code y él instalará, compilará y configurará todo por ti:

Install and configure the mail-mcp MCP server from https://github.com/tecnologicachile/mail-mcp

1. Clone the repo, build with cargo build --release
2. Add the MCP server to .claude.json with the binary path
3. For Microsoft accounts: use EWS (simplest) — run device code flow with
   client_id d3590ed6-52b3-4102-aeff-aad2292ab01c and scope
   https://outlook.office365.com/EWS.AccessAsUser.All offline_access
   Then configure MAIL_EWS_<ID>_USER and MAIL_EWS_<ID>_REFRESH_TOKEN
4. For Gmail: configure MAIL_IMAP + MAIL_SMTP with App Password from
   https://myaccount.google.com/apppasswords
5. For Zoho: configure MAIL_IMAP + MAIL_SMTP with standard password
6. Enable write/send: MAIL_IMAP_WRITE_ENABLED=true, MAIL_SMTP_WRITE_ENABLED=true

My email accounts to configure:
- <your-email@example.com>

Reemplaza la última línea con tu(s) correo(s). Claude Code te guiará a través de cada paso, incluido el flujo de código de dispositivo OAuth2 para cuentas de Microsoft.

Configuración Manual (2 minutos)

git clone https://github.com/tecnologicachile/mail-mcp.git
cd mail-mcp
cargo build --release

Agrega a la configuración de tu cliente MCP (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "mail": {
      "command": "./target/release/mail-mcp",
      "env": {
        "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
        "MAIL_IMAP_DEFAULT_USER": "you@gmail.com",
        "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
        "MAIL_SMTP_DEFAULT_PORT": "587",
        "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
        "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_SECURE": "starttls",
        "MAIL_IMAP_WRITE_ENABLED": "true",
        "MAIL_SMTP_WRITE_ENABLED": "true"
      }
    }
  }
}

Eso es todo. Tu agente de IA ahora puede leer, buscar, enviar, responder y gestionar correos.

¿Cuenta de Microsoft? Usa la API Graph

Microsoft bloquea SMTP en cuentas personales. Usa la API Graph en su lugar:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "outlook.office365.com",
    "MAIL_IMAP_DEFAULT_USER": "you@hotmail.com",
    "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
    "MAIL_OAUTH2_DEFAULT_PROVIDER": "microsoft",
    "MAIL_OAUTH2_DEFAULT_CLIENT_ID": "9e5f94bc-e8a4-4e73-b8be-63364c29d753",
    "MAIL_OAUTH2_DEFAULT_CLIENT_SECRET": "none",
    "MAIL_OAUTH2_DEFAULT_REFRESH_TOKEN": "<your-token>"
  }
}

Obtén tu token en 1 minuto con el flujo de código de dispositivo. Consulta Guía de Configuración de Cuenta.

31 Herramientas MCP

Lectura (9 herramientas)

Herramienta	Qué hace
`list_all_accounts`	Lista todas las cuentas con capacidades (IMAP, SMTP, Graph, EWS)
`imap_list_accounts`	Lista cuentas IMAP
`imap_verify_account`	Prueba conectividad y autenticación
`imap_list_mailboxes`	Lista carpetas
`imap_mailbox_status`	Conteos de mensajes
`imap_search_messages`	Búsqueda con paginación por cursor
`imap_get_message`	Mensaje analizado (texto, HTML, adjuntos)
`imap_get_message_raw`	Fuente RFC822
`imap_get_attachment`	Descarga un adjunto al disco (omite el límite de tamaño crudo)

Escritura (11 herramientas)

Herramienta	Qué hace
`imap_update_message_flags`	Agregar/quitar banderas
`imap_copy_message`	Copiar (multi-cuenta compatible)
`imap_move_message`	Mover a carpeta
`imap_delete_message`	Eliminar con confirmación
`imap_create_mailbox`	Crear carpeta
`imap_delete_mailbox`	Eliminar carpeta
`imap_rename_mailbox`	Renombrar carpeta
`imap_append_message`	Anexar mensaje crudo
`imap_bulk_move`	Mover hasta 500 a la vez
`imap_bulk_delete`	Eliminar hasta 500 a la vez
`imap_bulk_update_flags`	Marcar hasta 500 a la vez

Envío (5 herramientas)

Herramienta	Qué hace
`smtp_send_message`	Enviar correo (texto/HTML, CC/CCO)
`smtp_reply_message`	Responder con encabezados de hilo
`smtp_forward_message`	Reenviar con original en línea
`smtp_verify_account`	Probar conectividad SMTP
`graph_send_message`	Enviar vía API Graph de Microsoft (con hilo de respuesta)

EWS — Exchange Web Services (3 herramientas)

Herramienta	Qué hace
`ews_search_messages`	Buscar correos vía EWS (bandeja de entrada, enviados, borradores, etc.)
`ews_get_message`	Obtener contenido completo del correo vía EWS
`ews_send_message`	Enviar correo vía EWS

Adjuntos

Envía archivos con cualquier herramienta de envío. Dos modos:

// Large files — MCP reads from disk (recommended)
"attachments": [{"file_path": "/path/to/report.pdf"}]

// Small files — inline base64
"attachments": [{"filename": "note.txt", "content_type": "text/plain", "content_base64": "SGVsbG8="}]

El nombre de archivo y el tipo MIME se detectan automáticamente desde la ruta del archivo. Responde con include_original_attachments: true para reenviar adjuntos originales.

Descargar un adjunto de un mensaje recibido: usa imap_get_attachment con el message_id y un part_id (de imap_get_message) o filename. Escribe el archivo decodificado en disco y devuelve la ruta — sin límite de tamaño, y el binario permanece fuera de la respuesta. Establece el directorio de descarga predeterminado con MAIL_ATTACHMENT_DOWNLOAD_DIR (se respalda al directorio temporal del sistema), o pasa output_dir por llamada.

Operaciones Masivas (2 herramientas)

Herramienta	Qué hace
`imap_search_and_move`	Buscar + mover coincidencias
`imap_search_and_delete`	Buscar + eliminar coincidencias

Asistente de Configuración (1 herramienta)

Herramienta	Qué hace
`get_setup_guide`	Instrucciones de configuración específicas del proveedor (Microsoft OAuth2, Contraseñas de Aplicación de Gmail/iCloud, Zoho, etc.)

Multi-Cuenta

Configura tantas cuentas como necesites:

# Gmail
MAIL_IMAP_GMAIL_HOST=imap.gmail.com
MAIL_IMAP_GMAIL_USER=me@gmail.com
MAIL_IMAP_GMAIL_PASS=app-password

# Apple iCloud (App-Specific Password from appleid.apple.com)
MAIL_IMAP_ICLOUD_HOST=imap.mail.me.com
MAIL_IMAP_ICLOUD_USER=you@icloud.com
MAIL_IMAP_ICLOUD_PASS=app-specific-password
MAIL_SMTP_ICLOUD_HOST=smtp.mail.me.com
MAIL_SMTP_ICLOUD_USER=you@icloud.com
MAIL_SMTP_ICLOUD_PASS=app-specific-password
MAIL_SMTP_ICLOUD_SECURE=starttls

# Microsoft 365
MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_USER=me@company.com
MAIL_OAUTH2_WORK_PROVIDER=microsoft
MAIL_OAUTH2_WORK_CLIENT_ID=your-client-id
MAIL_OAUTH2_WORK_CLIENT_SECRET=none
MAIL_OAUTH2_WORK_REFRESH_TOKEN=your-token

# Zoho
MAIL_IMAP_DEFAULT_HOST=imap.zoho.com
MAIL_IMAP_DEFAULT_USER=info@mydomain.com
MAIL_IMAP_DEFAULT_PASS=password
MAIL_SMTP_DEFAULT_HOST=smtp.zoho.com
MAIL_SMTP_DEFAULT_USER=info@mydomain.com
MAIL_SMTP_DEFAULT_PASS=password
MAIL_SMTP_DEFAULT_SECURE=starttls

Usa account_id en llamadas de herramienta: "account_id": "gmail", "account_id": "icloud", "account_id": "work", "account_id": "default".

Seguridad

TLS obligatorio en todas las conexiones (excepto proxies de localhost)
Contraseñas en SecretString — nunca registradas ni devueltas en respuestas
Operaciones de escritura restringidas — requieren MAIL_IMAP_WRITE_ENABLED=true explícito
Operaciones de envío restringidas — requieren MAIL_SMTP_WRITE_ENABLED=true explícito
Confirmación de eliminación — requiere confirm: true
HTML sanitizado con ammonia (previene XSS)
Salidas limitadas — texto del cuerpo, HTML, adjuntos truncados a límites configurables
Tokens OAuth2 en caché con margen de actualización de 10 minutos
Sin secretos en respuestas — credenciales nunca expuestas vía herramientas MCP

Referencia de Configuración

Referencia completa de variables de entorno

IMAP (por cuenta)

Variable	Requerida	Predeterminado	Descripción
`MAIL_IMAP_<ID>_HOST`	Sí	—	Servidor IMAP
`MAIL_IMAP_<ID>_PORT`	No	993	Puerto IMAP
`MAIL_IMAP_<ID>_USER`	Sí	—	Nombre de usuario
`MAIL_IMAP_<ID>_PASS`	Sí*	—	Contraseña (*opcional con OAuth2)
`MAIL_IMAP_<ID>_SECURE`	No	true	Usar TLS

SMTP (por cuenta)

Variable	Obligatorio	Predeterminado	Descripción
`MAIL_SMTP_<ID>_HOST`	Sí	—	Servidor SMTP
`MAIL_SMTP_<ID>_PORT`	No	587	Puerto SMTP
`MAIL_SMTP_<ID>_USER`	Sí	—	Nombre de usuario
`MAIL_SMTP_<ID>_PASS`	No	—	Contraseña (opcional con OAuth2)
`MAIL_SMTP_<ID>_SECURE`	No	starttls	`starttls`, `tls` o `plain`
`MAIL_SMTP_<ID>_FROM_EMAIL`	No	= `_USER`	Dirección del remitente cuando difiere del nombre de usuario de autenticación SMTP (p. ej., buzones compartidos/grupales)

OAuth2 (por cuenta)

Variable	Obligatorio	Predeterminado	Descripción
`MAIL_OAUTH2_<ID>_PROVIDER`	Sí	—	`google` o `microsoft`
`MAIL_OAUTH2_<ID>_CLIENT_ID`	Sí	—	ID de cliente OAuth2
`MAIL_OAUTH2_<ID>_CLIENT_SECRET`	Sí	—	Secreto del cliente (`none` para clientes públicos)
`MAIL_OAUTH2_<ID>_REFRESH_TOKEN`	Sí	—	Token de actualización

OAuth2 de Graph API (por cuenta)

Variable	Obligatorio	Predeterminado	Descripción
`MAIL_GRAPH_<ID>_PROVIDER`	Sí	—	`microsoft`
`MAIL_GRAPH_<ID>_CLIENT_ID`	Sí	—	ID de cliente OAuth2
`MAIL_GRAPH_<ID>_CLIENT_SECRET`	Sí	—	Secreto del cliente (`none` para clientes públicos)
`MAIL_GRAPH_<ID>_REFRESH_TOKEN`	Sí	—	Token de actualización (ámbito Mail.Send)

EWS — Exchange Web Services (por cuenta, el más simple para Microsoft)

Variable	Obligatorio	Predeterminado	Descripción
`MAIL_EWS_<ID>_USER`	Sí	—	Dirección de correo electrónico
`MAIL_EWS_<ID>_REFRESH_TOKEN`	Sí	—	Token de actualización OAuth2 (ámbito EWS)
`MAIL_EWS_<ID>_CLIENT_ID`	No	`d3590ed6...` (Microsoft Office)	ID de cliente OAuth2
`MAIL_EWS_<ID>_CLIENT_SECRET`	No	`none`	Secreto del cliente

Consejo: EWS solo necesita 2 variables (USER + REFRESH_TOKEN). El ID de cliente se establece por defecto en Microsoft Office, que tiene todos los permisos preaprobados.

Configuración global

Variable	Predeterminado	Descripción
`MAIL_IMAP_WRITE_ENABLED`	false	Habilitar operaciones de escritura IMAP
`MAIL_SMTP_WRITE_ENABLED`	false	Habilitar operaciones de envío SMTP/Graph
`MAIL_SMTP_SAVE_SENT`	false	Guardar correos enviados en la carpeta de Enviados de IMAP (habilítalo si tu proveedor no guarda automáticamente al enviar; p. ej., Gmail sí lo hace, Zoho no siempre)
`MAIL_SMTP_CONNECT_TIMEOUT_MS`	30000	Tiempo de espera de TCP/TLS/autenticación SMTP (fase de conexión)
`MAIL_SMTP_SEND_TIMEOUT_MS`	300000	Tiempo de espera de transmisión de datos SMTP (5 min — admite archivos adjuntos grandes)
`MAIL_SMTP_TIMEOUT_MS`	(obsoleto)	Tiempo de espera único heredado. Se respeta como respaldo para `MAIL_SMTP_SEND_TIMEOUT_MS`. Prefiere las variables divididas anteriores.
`MAIL_IMAP_CONNECT_TIMEOUT_MS`	30000	Tiempo de espera de conexión TCP
`MAIL_IMAP_GREETING_TIMEOUT_MS`	15000	Tiempo de espera de saludo TLS
`MAIL_IMAP_SOCKET_TIMEOUT_MS`	300000	Tiempo de espera de E/S de socket

Hoja de ruta

Siguiente — Caché local con búsqueda instantánea

Caché de correo local SQLite + FTS5 — búsquedas instantáneas (<10 ms frente a 3-10 s)
Sincronización incremental — sincronización delta UIDVALIDITY + último UID
Agrupación de conexiones — sesiones IMAP persistentes por cuenta
Búsqueda entre cuentas — buscar en todas las cuentas a la vez
Estadísticas de correo — recuentos, remitentes principales, actividad por fecha

Futuro

Documentación

Guía	Descripción
Configuración de cuentas	Paso a paso por proveedor, OAuth2, contraseñas de aplicación, ID de cliente de Azure
Contrato de herramientas	Definiciones y esquemas completos de herramientas
Formato de ID de mensaje	Formato estable de identificador de mensaje
Paginación por cursor	Comportamiento y caducidad de la paginación
Seguridad	Funciones de seguridad y mejores prácticas
Configuración avanzada	Tiempos de espera y ajuste de rendimiento

Desarrollo

cargo test              # 64 unit + integration tests
cargo fmt -- --check    # formatting
cargo clippy --all-targets -- -D warnings  # linting

Consulta AGENTS.md para las pautas de contribución.

Publicación de versiones

Las versiones se automatizan mediante cargo-dist. Para publicar una nueva versión:

Incrementa version = "X.Y.Z" en Cargo.toml (el flujo de trabajo de publicación exige que coincida con la etiqueta enviada).
Confirma el incremento y cualquier nota de versión en main.

Etiqueta y envía:

git tag vX.Y.Z
git push origin main --tags

El desencadenador push: tags: ['v*'] en .github/workflows/release.yml compila binarios para Linux / macOS (Intel + Apple Silicon) / Windows, genera scripts de instalación (.sh, .ps1), crea la versión de GitHub y adjunta todos los artefactos con sumas de verificación SHA256.
Si algo falla, puedes volver a ejecutar el flujo de trabajo manualmente desde la pestaña Acciones (el desencadenador workflow_dispatch se conserva como vía de escape).

La publicación en npm está deshabilitada intencionalmente. La bifurcación ascendente estaba configurada para publicar como @bradsjm/mail-imap-mcp-rs, un ámbito que esta organización no posee, lo que provocaba que cada versión diera error 404 en npm publish. El paquete npm todavía se genera y se adjunta a cada versión de GitHub para que los usuarios puedan instalarlo mediante npm install ./mail-mcp-npm-package.tar.gz manualmente. Para habilitar la publicación en el registro npm para esta bifurcación: crea una organización npm (p. ej., @tecnologicachile), configura Publicación de confianza en npmjs.com apuntando a este repositorio, establece publish-jobs = ["npm"] en dist-workspace.toml y ejecuta dist generate --allow-dirty para restaurar el trabajo publish-npm en release.yml.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta los problemas para encontrar buenos primeros problemas.

Licencia

Licencia MIT — consulta LICENCIA para más detalles.