Apple Mail MCP

Apple Mail MCP

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

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

Inicio rápido

Claude Code (plugin)

claude plugin marketplace add imdinu/apple-mail-mcp
claude plugin install apple-mail@imdinu

Claude Desktop (paquete de un clic)

Descarga apple-mail-mcp-<version>.mcpb desde el último lanzamiento y haz doble clic en él.

Tanto el plugin como el paquete ejecutan el paquete PyPI publicado mediante un lanzador ligero (uvx → pipx → venv privado, el que esté disponible) — sin código incluido, comportamiento idéntico a una instalación manual. Inician el servidor con --watch; concede Acceso Completo al Disco a la aplicación lanzadora (Claude Code / Claude Desktop) para que el índice se mantenga actualizado.

Cualquier cliente MCP

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 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 otros 6 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 búsqueda de cuerpo en absoluto; el que sí lo hace (BastianZim) escanea en vivo solo los 5000 mensajes más recientes — fallo silencioso en cualquier cosa más antigua. Nuestro índice FTS5 cubre todo el buzón.
• ~3ms de recuperación de un solo correo mediante lectura .emlx de disco primero (sin ida y vuelta JXA).
• ~1ms list_accounts y ~5ms de listado de 50 correos mediante lecturas directas de SQLite del Índice de Envolventes (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 de espera, lanzan errores de sintaxis u omiten operaciones que no admiten.

Configuración

Apple Mail MCP funciona de inmediato. 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 mediante 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 (sin necesidad de 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-o-posterior