Apple Mail MCP

Apple Mail MCP

El único servidor Apple Mail MCP con búsqueda de cuerpo de cobertura completa — confiable en buzones grandes donde los servidores basados en AppleScript agotan el tiempo. 8 herramientas para leer, buscar y extraer contenido de correos electrónicos.

Lee la documentación para la guía completa.

Inicio rápido

pipx install apple-mail-mcp

Añade a tu cliente MCP:

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp"
    }
  }
}

Construir el índice de búsqueda (Recomendado)

# Requires Full Disk Access for Terminal
# System Settings → Privacy & Security → Full Disk Access → Add Terminal

apple-mail-mcp index --verbose

Configurar (Opcional)

apple-mail-mcp init   # writes ~/.apple-mail-mcp/config.toml

Escribe un archivo de configuración comentado que puedes editar para establecer valores predeterminados como tu cuenta principal o buzón. Cada clave tiene una variable de entorno APPLE_MAIL_* correspondiente si prefieres la configuración basada en el entorno. Consulta Configuración para el esquema completo y las reglas de precedencia.

Herramientas

Herramienta	Propósito
list_accounts()	Listar cuentas de correo
list_mailboxes(account?)	Listar buzones
get_emails(filter?, limit?)	Obtener correos — todos, no leídos, marcados, hoy, últimos_7_días
get_email(message_id)	Obtener un solo correo con contenido completo + adjuntos
search(query, scope?, before?, after?, highlight?)	Buscar — todos, asunto, remitente, cuerpo, adjuntos
get_email_links(message_id)	Extraer enlaces de un correo
get_email_attachment(message_id, filename)	Extraer contenido de adjuntos
get_attachment(message_id, filename)	Obsoleto — usa get_email_attachment()

Rendimiento

Probado contra 6 otros servidores Apple Mail MCP en un buzón real de ~73K mensajes:

• Único servidor con búsqueda de cuerpo de cobertura completa. La mayoría de los competidores no admiten la búsqueda de cuerpo en absoluto; el que lo hace (BastianZim) escanea en vivo solo los 5000 mensajes más recientes — falla silenciosa en cualquier cosa más antigua. Nuestro índice FTS5 cubre todo el buzón.
• ~3ms de recuperación de un solo correo mediante lectura de .emlx primero en disco (sin ida y vuelta JXA).
• ~1ms list_accounts y ~5ms de listado de 50 correos mediante lecturas directas de Envelope-Index SQLite (0.4+) — el mismo camino que usan BastianZim/rusty/pl-lyfx, con JXA como respaldo de corrección.
• ~7ms de búsqueda por asunto mediante FTS5 — competitivo con Rust nativo en la misma operación.
• Confiable en las 6 operaciones evaluadas en un buzón de 73K; los servidores basados en AppleScript agotan el tiempo, lanzan errores de sintaxis u omiten operaciones que no admiten.

Configuración

Apple Mail MCP funciona de fábrica. Para personalizar los valores predeterminados, ejecuta apple-mail-mcp init para generar una plantilla config.toml — o usa las variables de entorno APPLE_MAIL_* correspondientes. Consulta la documentación de configuración para el esquema completo y la precedencia CLI > env > archivo > predeterminado.

Las anulaciones de entorno por cliente a través de la configuración de lanzamiento del cliente MCP también funcionan:

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "args": ["--watch"],
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

Uso de CLI

Todas las herramientas también están disponibles como comandos CLI independientes (no se necesita servidor MCP):

apple-mail-mcp search "quarterly report" --scope subject
apple-mail-mcp search "invoice" --after 2026-01-01 --limit 10
apple-mail-mcp read 12345
apple-mail-mcp emails --filter unread --limit 10
apple-mail-mcp accounts
apple-mail-mcp mailboxes --account Work
apple-mail-mcp extract 12345 invoice.pdf

Todos los comandos generan JSON. Genera una habilidad de Claude Code para acceso basado en CLI:

apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md

Desarrollo

git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync
uv run ruff check src/
uv run pytest

Licencia

GPL-3.0-or-later