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 administrar correos electrónicos en macOS.

⚠️ Pre-1.0 — espera cambios que rompan la compatibilidad. La superficie de herramientas MCP (nombres de herramientas, parámetros, formatos de retorno) todavía está evolucionando a medida que el proyecto madura. Fija una versión específica (por ejemplo, apple-mail-mcp==0.8.1) y revisa el CHANGELOG antes de actualizar.

Herramientas (23)

Núcleo: list_mailboxes, search_messages, get_messages, update_message Ciclo de vida de borradores: create_draft, update_draft, delete_draft CRUD de buzones: create_mailbox, update_mailbox, delete_mailbox Adjuntos y gestión: save_attachments, delete_messages Descubrimiento y reglas: list_accounts, list_rules, get_thread, create_rule, update_rule, delete_rule Plantillas: list_templates, get_template, save_template, delete_template, render_template

Consulta la documentación completa sobre parámetros y formatos de retorno en docs/reference/TOOLS.md.

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/s-morgan-jeffries/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

Configuración

Añade a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}

Permisos

En la primera ejecución, macOS solicitará 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 de serie mediante AppleScript. Para buzones grandes (miles de mensajes), la cláusula whose de AppleScript puede tardar de 1 a 5 segundos por consulta. Si quieres una búsqueda más rápida del lado del servidor, puedes habilitar la delegación IMAP por cuenta añadiendo una entrada en Keychain.

Cómo funciona. Si existe una entrada en Keychain para una cuenta, el servidor usa IMAP (búsqueda rápida en el servidor). En caso contrario —o si se produce cualquier error de IMAP (sin conexión, contraseña incorrecta, tiempo de espera agotado)— vuelve a AppleScript en silencio. Nunca pierdes funciones; solo ganas velocidad cuando IMAP está configurado y es accesible. Sin indicadores de configuración, sin variables de entorno; la presencia de la entrada en Keychain es la activación voluntaria.

Configuración única por cuenta.

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

   • iCloud: appleid.apple.com/account/manage → Contraseñas específicas para la app. Requiere la autenticación de dos factores (2FA) en tu Apple ID (por defecto).

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

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

2. Ejecuta el subcomando setup-imap. Te pedirá la contraseña (sin eco), escribe la entrada en Keychain y lo verifica conectándose:

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

   Sustituye el nombre de la cuenta de Mail.app exactamente — tal y como está etiquetada en Mail.app (p. ej., iCloud, Gmail, "Yahoo!"). El CLI:

   • busca el correo principal de la cuenta en Mail.app (se puede reemplazar con --email),

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

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

   • abre una conexión IMAP y ejecuta un LOGIN real para confirmar que la contraseña funciona. Si es rechazada, revierte la entrada de Keychain para que puedas reintentarlo sin dejar un elemento roto.

3. Si ves un aviso único de «security wants to use the 'login' keychain» en la siguiente llamada respaldada por IMAP, haz clic en Permitir siempre.

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

Verificación de la configuración. El comando setup-imap hace esto por ti. Si quieres comprobarlo manualmente a posteriori:

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 regresa en aproximadamente 1 segundo. Si registra un WARNING sobre el mecanismo de respaldo (visible con --log-level=DEBUG), comprueba que el nombre de la cuenta coincida exactamente con el nombre de la cuenta en Mail.app y que el correo de tu entrada en Keychain coincida con lo que devuelve email addresses of account.

Peculiaridades conocidas de los proveedores.

• iCloud: el servidor IMAP acepta los alias @icloud.com / @me.com como nombre de usuario de LOGIN, no el email del Apple ID. Por eso el servidor (y setup-imap) lee email addresses of account de Mail.app.

• Yahoo: las contraseñas de aplicación se han ido depreciando progresivamente; la opción puede no estar disponible para todas las cuentas. Si la página de seguridad de Yahoo no ofrece la opción, no se puede configurar IMAP con esa cuenta y AppleScript es la única vía.

• Gmail: requiere la verificación en dos pasos. Si tu administrador de Google Workspace ha desactivado las contraseñas de aplicación para todo el espacio, no se puede configurar IMAP en esa cuenta.

• Obtención de hilos de Gmail: compensación con la visibilidad de All Mail. find_thread_members (usado internamente por las consultas que tienen en cuenta los hilos) es más rápido cuando [Gmail]/All Mail está expuesto a través de IMAP: ese camino requiere una 5 turnos de ida y vuelta, independientemente del número de buzones. Muchos usuarios ocultan All Mail (Configuración de Gmail → Reenvío y POP/IMAP → Límites de tamaño de carpeta → "Do not show in IMAP" porque duplica todos los mensajes. Cuando está oculta, el conector recurre a una iteración X-GM-THRID por buzón (todavía unas ~6 veces más rápida que el BFS universal, pero proporcional al número de etiquetas: ~25 s en una cuenta con 92 etiquetas). Expón All Mail si quieres la máxima velocidad; déjala oculta si prefieres una lista de carpetas IMAP más limpia.

Operaciones de escritura (create_draft, update_draft, incluida la ruta de envío con send_now=true) usan siempre AppleScript, independientemente de la configuración de IMAP, porque necesitan del borrador de Mail.app.

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)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app

• server.py — Registro de herramientas de MCP, validación de entradas y formato de respuestas

• mail_connector.py — Toda la generación y ejecución de AppleScript

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

• utils.py — Funciones puras: escape, análisis, validación

• exceptions.py — Jerarquía de excepciones tipadas

Seguridad

• Ejecución solo local (sin procesamiento en nube)

• Usa la autenticación existente a Mail.app (sin almacenamiento de credenciales)

• Todas las entradas se sanitizan y se escapan para AppleScript

• Las operaciones destructivas requieren confirmación

• Registro de auditoría de operaciones

• Consulta SECURITY.md para la política y docs/SECURITY.md para un análisis detallado

Contribuciones

Consulta CONTRIBUTING.md para conocer el flujo de desarrollo, los estándares de código y el proceso de PR.

Licencia

MIT