Apple Mail MCP Server

Un servidor MCP que proporciona acceso programático a Apple Mail, lo que permite a asistentes de IA como Claude leer, enviar, buscar y gestionar correos electrónicos en macOS.

⚠️ Pre-1.0: se esperan cambios que rompen la compatibilidad. La superficie de herramientas MCP (nombres de herramientas, parámetros, formas de retorno) sigue en evolución conforme el proyecto madura. Fija una versión concreta (por ejemplo, apple-mail-mcp==0.10.2) y revisa el CHANGELOG antes de actualizar.

Herramientas (29)

Agrupadas por ciclo de vida (10 de solo lectura, 19 de modificación):

• Descubrimiento — list_accounts, list_mailboxes, list_rules, list_templates: enumeran lo que está configurado (sin caché externa: llamar por cuenta).

• Lectura — search_messages, get_messages, get_thread, get_attachment_content, get_template, render_template: leen mensajes e hilos, obtienen el contenido de un adjunto en línea y renderizan plantillas.

• Acciones sobre mensajes — update_message (marcar como leído, marcar con bandera o mover en una sola operación), delete_messages (→ Papelera), save_attachments (a disco, con límite de bytes).

• Borradores — create_draft (nuevo / responder / reenviar, opcionalmente send_now), update_draft, delete_draft.

• Envío directo — send_email, reply, reply_all, forward: envían en una sola llamada, sin pasar por un borrador. Cada una envía de verdad; no hay un segundo paso de confirmación dentro de Mail.

• Cuentas — delete_account: elimina una cuenta configurada de Mail.app.

• CRUD de buzones — create_mailbox, update_mailbox (renombrar o mover), delete_mailbox.

• Reglas — create_rule, update_rule, delete_rule.

• Plantillas (escritura) — save_template, delete_template.

Las operaciones destructivas (delete_*, create_rule con acciones de mover/reenviar/eliminar, create_draft con send_now=true) piden confirmación mediante el mecanismo de confirmación de MCP. Consulta docs/reference/TOOLS.md para los parámetros completos y las estructuras de retorno.

Related MCP server: apple-mail-mcp

Requisitos previos

• macOS 10.15 (Catalina) o posterior

• Python 3.10 o posterior

• Apple Mail configurado con al menos una cuenta

• uv (recomendado) o pip

Instalación

# From source (recommended for development)
git clone https://github.com/LeChabrax/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

Configuración

Añádelo a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json). uv sync instala un script de consola en .venv/bin/apple-mail-mcp; apunta Claude Desktop a su ruta absoluta — es la forma más estable en el entorno de ejecución restringido de Claude Desktop (no depende de que uv esté en el PATH):

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

(Alternativa equivalente, si prefieres ejecutarlo a través de uv: "command": "uv", "args": ["--directory", "/path/to/apple-mail-mcp", "run", "apple-mail-mcp"].)

Opcional: dividir servidores de lectura / escritura

Claude Desktop pide permiso por herramienta. Si quieres aprobar en lote las 10 herramientas de lectura (list / search / get) y seguir restringiendo las 19 herramientas de modificación por llamada, ejecuta el conector dos veces — una con --read-only, otra sin él — en dos entradas mcpServers distintas:

{
  "mcpServers": {
    "apple-mail-read": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp",
      "args": ["--read-only"]
    },
    "apple-mail-write": {
      "command": "/path/to/apple-mail-mcp/.venv/bin/apple-mail-mcp"
    }
  }
}

El servidor --read-only expone solo las 10 herramientas de lectura, por lo que la interfaz de permisos por servidor de Claude Desktop las agrupa de forma natural. El servidor completo sigue restringiendo las operaciones de escritura de forma individual. A cambio: 2× procesos del conector. Consulta docs/reference/TOOLS.md para la clasificación por herramienta y una nota sobre las anotaciones MCP (readOnlyHint / destructiveHint / idempotentHint) que los hosts compatibles pueden usar para ofrecer la misma experiencia de usuario sin tener que dividir el servidor.

Permisos

En la primera ejecución, macOS pedirá acceso a Automatización. Concede el permiso en: Ajustes del Sistema > Privacidad y seguridad > Automatización > Terminal (o tu IDE)

Opcional: búsqueda más rápida mediante IMAP

search_messages funciona sin configuración adicional mediante AppleScript. En buzones grandes (miles de mensajes), la cláusula whose de AppleScript puede tardar entre 1 y 5 segundos por consulta. Si quieres una búsqueda más rápida en el servidor, puedes activar la delegación IMAP por cuenta añadiendo una entrada en el Llavero (Keychain).

Cómo funciona. Si existen credenciales para una cuenta, el servidor usa IMAP (búsqueda SEARCH rápida del lado del servidor). En caso contrario — o ante cualquier fallo de IMAP (desconexión, contraseña incorrecta, temporización agotada) — recurre silenciosamente a AppleScript. Nunca pierdes funcionalidad; solo ganas velocidad cuando IMAP está configurado y es accesible. La activación normal es mediante una entrada en el Llavero (más abajo); hay una alternativa mediante variable de entorno (más abajo) para contextos donde el Llavero no es utilizable.

Configuración única por cuenta.

1. Genera una contraseña específica de aplicación en tu proveedor. El procedimiento varía:

   • iCloud: appleid.apple.com/account/manage → Contraseñas específicas de aplicación. Requiere la autenticación de doble factor (2FA) en tu Apple ID (configuración predeterminada).

   • Gmail: myaccount.google.com/apppasswords. Requiere la verificación en dos pasos en tu cuenta de Google.

   • Yahoo / Fastmail / AOL: genera una contraseña de aplicación en la configuración de seguridad de la cuenta del proveedor.

2. Ejecuta el subcomando setup-imap. Solicita la contraseña (sin eco), escribe la entrada en el Llavero y verifica la conexión:

   apple-mail-mcp setup-imap --account iCloud

   Sustituye el nombre de la cuenta por el nombre exacto que aparece en Mail.app (por ejemplo, iCloud, Gmail, "Yahoo!"). El CLI:

   • busca la dirección de correo principal de la cuenta en Mail.app (puedes omitir el valor con --email, que se conserva para que el tiempo de ejecución use el mismo inicio de sesión — considera la peculiaridad de iCloud más abajo),

   • solicita la contraseña mediante getpass para que nunca quede en el historial del shell,

   • escribe en el Llavero en apple-mail-mcp.imap.<account> (idempotente: al volver a ejecutarlo con una contraseña nueva se actualiza la entrada existente),

   • abre una conexión IMAP y ejecuta un LOGIN real para confirmar que la contraseña funciona. Si se rechaza, elimina la entrada del Llavero para que puedas reintentar sin dejar una entrada rota.

3. Si en la siguiente llamada con IMAP ves un aviso único de «security quiere usar el llavero “login”», haz clic en Permitir siempre.

Para eliminar la entrada más adelante: apple-mail-mcp setup-imap --account iCloud --option --uninstall— mejorapple-mail-mcp setup-imap --account iCloud --uninstall`.

Alternativa mediante variable de entorno (uvx / headless / CI)

Algunos contextos no tienen un Llavero utilizable: las ejecuciones con uvx (los caminos efímeros de los binarios rompen la ACL del Llavero, lo que provoca que vuelvan a pedir permisos o que falle), Docker / CI (no hay Llavero en absoluto) y los servicios en segundo plano (la solicitud de ACL se queda bloqueada indefinidamente sin interfaz). Para estos casos, puedes aportar la contraseña IMAP mediante una variable de entorno:

APPLE_MAIL_MCP_IMAP_PASSWORD_<SUFFIX>

El <SUFFIX> es el nombre de la cuenta en Mail.app en mayúsculas, con cada aparición de caracteres no alfanuméricos reducidos a un único guion bajo y sin guiones bajos al principio ni al final:

Cuando esté ajustado a un valor no vacío, la variable de entorno se usa con prioridad sobre cualquier entrada del Llavero para esa cuenta (se comprueba primero, sin recurrir a security). Un valor vacío (o solo con espacios) se ignora y se usa la ruta del Llavero. Esta búsqueda se combina con el nombre↔UUID, por lo que una variable de entorno anclada al nombre de la cuenta se encuentra igual cuando se pase el UUID de la cuenta.

⚠️ Truegue de seguridad. Las variables de entorno son mucho menos privadas que el Llavero: se ven mediante ps -E, launchctl getenv, la introspectora estilo /proc y los volcados de memoria de procesos. Es fácil que se escapen a registros o al historial del shell. Usa esto solo cuando el Llavero no sea realmente una opción (uvx, Docker, CI, headless). Para Claude Desktop y las instalaciones locales habituales, mantén setup-imap + Llavero.

Advertencia: El mapeo nombre→sufijo no es reversible; Yahoo! y Yahoo se asignan a YAHOO, y un nombre de cuenta sin letras/dígitos no ASCII no tiene su forma variable (usa el Llavero para esas).

Verificación de la configuración. El comando setup-imap lo hace por ti. Si quieres comprobarlo posteriormente:

uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

Si IMAP funciona, la llamada devuelve en ~1 segundo. Si registra una advertencia sobre la caída al respaldo (visible con --log-level=DEBUG), comprueba que el nombre de la cuenta coincide exactamente con el nombre de la cuenta en Mail.app y que el correo lateral de tu entrada del Llavero coincide con el que devuelve cuentas de email de la cuenta.

Peculiaridades de los proveedores conocidas.

• iCloud: el servidor IMAP acepta los alias @icloud.com / @me.com como nombre de usuario LOGIN, no el email del Apple ID. Por ese motivo, el servidor (y setup-imap) lee email addresses of account de Mail.app. Si tu Apple ID de iCloud y una dirección de tercero (por ejemplo, un Apple ID con un correo @gmail.com) y Mail.app no comunica ninguna dirección @icloud.com para la cuenta, la detección automática no puede encontrar el inicio de sesión correcto. setup-imap fallará con una pista para que vuelvas a ejecutarlo con --email <tu dirección @icloud.com/@me.com> que la dirección. Ese valor de --email se guarda (en ~/.apple_mail_mor vigente ~/.apple_mail_mcp/imap_login_overrides.json) para que el tiempo de ejecución use el mismo login (#341). Es una pasarela general: dispones para cualquier cuenta cuyo inicio de sesión no se robusto automáticamente sea incorrecto.

• Yahoo: las contraseñas de aplicación se han ido retirando progresivamente; puede que la opción no esté disponible para todas las cuentas. Si la página de seguridad de la cuenta Yahoo no muestra la opción, la la instalación IMAP no es posible para esa cuenta y AppleScript es la única vía.

• Gmail: necesita la verificación en dos pasos activa. Si el administrador de Google Workspace ha deshabilitado los correos de aplicación a nivel de arrendad (tenant), la configuración de IMAP no es posible para esa cuenta.

• Recoveración de hilos de Gmail — Intercambio entre ganancia y visibilidad de All Mail: find_thread_members (utilizado internamente por las consultas de hilo) es más rápido cuando [Gmail]/All Mail está expuesto en IMAP: esa ruta necesita ~5 conversaciones, independiente del número de buzones. Muchos usuarios ocultan All Mail (Ajustes de Gmail → Reenvío y POP/IMAP → Límites de tamaño de carpeta → “No mostrar en IMAP”) porque duplica todos los mensajes. Si está ocultado, el conector se cambia y de una iteración por buzón con X-GM-THRID (sigue siendo ~5× más rápida que el BFS universal, pero proporcional al número de etiquetas: ~2s a 25 una cuenta de 92 etiquetas). Expon All Mail si quieres la velocidad máxima; mantén secreto si prefieres la lista de buzones IMAP más limpio.

Las operaciones de escritura (create_draft, update_draft, incluida la vía save_path de send "en send_now") siempre usan AppleScript independientemente de la configuración IMAP: necesitan la interfaz de redacción de Mail.app.

Timeouts en buzones muy grandes

Los valores predeterminados están pensados durante los buzones ordinarios y es conveniente aumentarlos sobre uno grande. La medición propia de este módulo es de 148 s para 100 mensajes con caché en frío en un buzón de 47k mensajes, así que una SEARCH del lado servidor para superar el valor predeterminado de 30 s y recurrir silenciosamente al camino más lento de AppleScript.

Un valor que no sea número o que no sea positivo se ignora con un aviso y se mantiene el valor predeterminado, así que un error de escritura no puede tumbar el servidor.

Desarrollo

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

Convención de ramas

{type}/issue-{num}-{description} — p. ej., feature/issue-42-thread-support

Arquitectura

server.py (FastMCP tools — thin orchestration, validation, elicitation gates)
  -> mail_connector.py (dispatch + domain logic)
     -> AppleScript path:  subprocess.run(["osascript", ...]) -> Apple Mail.app   (universal baseline)
     -> IMAP fast path:    imap_connector.py -> the account's IMAP server          (when hinted + Keychain creds)

Modelo de despacho. AppleScript es la base siempre disponible. Cuando una llamada de lectura/mutación proporciona una pista de account (y, cuando corresponde, mailbox) y la cuenta tiene credenciales IMAP en Keychain, el conector toma una ruta rápida IMAP del lado del servidor; ante cualquier fallo de IMAP recurre a AppleScript, de modo que nunca pierdes funcionalidad, solo ganas velocidad. Consulta docs/reference/ARCHITECTURE.md para ver el modelo de despacho completo, el esquema de message-ID de doble emisión, el ciclo de vida de los borradores y los niveles de hilos IMAP.

• server.py — Registro de herramientas MCP, validación de entrada, compuertas de confirmación (elicitación), formato de respuestas

• mail_connector.py — Generación/ejecución de AppleScript + despacho por ruta rápida IMAP

• imap_connector.py — Cliente IMAP + grupo de conexiones (rutas rápidas de búsqueda, recuperación y mutación masiva)

• security.py — Saneamiento de entradas, registro de auditoría, flujos de confirmación

• utils.py — Funciones puras: escape, parseo, validación

• exceptions.py — Jerarquía de excepciones tipadas

Seguridad

• Solo ejecución local (sin procesamiento en la nube)

• Usa la autenticación existente de Mail.app; las contraseñas de aplicación IMAP (opt-in) residen en el Keychain de macOS, nunca en el repositorio ni en la configuración

• Todas las entradas se sanean y se escapan para AppleScript (defensa contra la inyección de AppleScript)

• Las operaciones destructivas requieren confirmación del usuario mediante elicitación de MCP; límites de tasa + registro de auditoría adicional

• save_attachments tiene un tope de bytes (por adjunto + agregado) contra DoS por llenado de disco

Documentación:

• SECURITY.md — política de notificación de vulnerabilidades

• docs/SECURITY.md — postura de seguridad y privacidad orientada al usuario

• docs/guides/THREAT_MODEL.md — análisis de límites de confianza STRIDE

• docs/guides/SECURITY_CHECKLIST.md — lista de verificación para contribuidores por funcionalidad

Contribuciones

Consulta CONTRIBUTING.md para conocer el flujo de trabajo de desarrollo, los estándares de codificación y el proceso de PR.

Créditos

Este proyecto es un fork de apple-mail-mcp de Morgan Jeffries, que hace todo el trabajo pesado: el puente de AppleScript, la ruta rápida IMAP, el almacén de estado de borradores, las plantillas y las compuertas de elicitación.

Lo que este fork añade sobre upstream v0.10.2:

Todo lo demás, incluida la superficie de herramientas, las pruebas y la documentación, proviene de upstream. Los informes de errores sobre las partes compartidas es mejor presentarlos allí.

Lo que Mail.app no permite que este servidor haga

Medido en macOS 15, conviene saberlo antes de abrir un issue:

• Una cuenta creada mediante AppleScript nunca se persiste. make new imap account devuelve un id y count of accounts la ve, pero no aparece en la ventana de Ajustes de Mail y desaparece cuando Mail se cierra. Para añadir una cuenta de verdad se necesita un perfil de configuración (com.apple.mail.managed), aprobado en pantalla. No hay una vía programática: profiles install responde "la herramienta profiles ya no admite instalaciones".

• enabled no se puede escribir en ninguna cuenta. set enabled lanza -10000 AppleEvent handler failed, tanto en una cuenta nueva como en una existente activa, mediante AppleScript y mediante JXA, con todas las formas de referencia. El propio sdef de Mail declara la propiedad escribible (sin access="r", clave Cocoa isActive); la implementación discrepa.

• La ventana de Ajustes de Mail es una instantánea obsoleta. Muestra cuentas que AppleScript ya no conoce y omite las que sí conoce. Nunca leas el estado de las cuentas desde la interfaz.

Licencia

MIT