Apple Mail

---

✨ Lo que puedes hacer

🔍 Haz preguntas a tu bandeja de entrada. "¿Qué me envió Stefan sobre el memo la semana pasada?" La búsqueda se ejecuta a velocidad de base de datos — remitente, buzón, fechas, no leídos, adjuntos — y reconstruye conversaciones completas.

🕳️ Encuentra lo que Mail no puede. La búsqueda integrada de Mail solo revisa la primera línea de la mayoría de los mensajes. apple-mail-mcp indexa el cuerpo de cada mensaje en tu Mac — y para cuentas de Exchange incluso obtiene los cuerpos que Mail nunca descargó, directamente desde tu propio buzón en el servidor. Las consultas que no devolvían nada devuelven veinte resultados.

🎭 Envía como el "tú" correcto. Correo de trabajo por la vía laboral, personal por Gmail — un parámetro elige la identidad. Cada mensaje se compone desde cero como correo limpio y conforme a estándares que se renderiza en todas partes, incluido Outlook (la ruta de composición de AppleScript que llega en blanco en Outlook es la razón por la que existe este proyecto).

⏰ Programa como "Enviar más tarde", pero con script. Un mensaje programado queda congelado por completo — adjuntos, identidad, texto exacto. Exchange puede ejecutarlo en el servidor a la hora solicitada, con la tapa cerrada; otros proveedores usan un remitente local en segundo plano y lo entregan en su siguiente pasada (o justo después de que el Mac se despierte).

🗂️ Clasifica a escala, sin miedo. "Archiva estos 40 boletines" se convierte en un plan revisable: nada se mueve hasta que se aprueba, cada mensaje se vuelve a verificar antes de tocarlo y el resultado se confirma contra los propios registros de Mail después. Eliminar significa Papelera de Mail — nada se borra jamás.

📝 Redacta donde viven tus borradores. Compón en tu carpeta real de Borradores de Exchange, lista para abrir en Outlook u OWA — creada, nunca enviada automáticamente.

⚡ Por qué es diferente

Cualquier otro MCP de Apple Mail usa AppleScript tanto para buscar como para actuar. Este no — y se nota:

Operación	AppleScript con cláusula whose	apple-mailbox-mcp
🔍 Buscar 300k mensajes	segundos hasta agotar tiempo	milisegundos
🎯 Dirigir un mensaje en un buzón de 71k	7–10 s (medido)	< 0.1 ms
✉️ Enviar correo	el cuerpo se renderiza en blanco en Outlook	se renderiza en todas partes, texto plano+HTML
⏰ Programar correo	—	en el servidor con Exchange; cola local confiable en cualquier otro lugar
🗂️ Clasificación masiva	una llamada por mensaje, sin seguimiento	un plan revisado, una aplicación, verificado

Cada número anterior se midió en un almacén real de ~300,000 mensajes; el script y el método completo están en docs/benchmarks.md.

Si los benchmarks se mantienen en tu buzón, una ⭐ ayuda a que otros lo encuentren.

🛡️ Diseñado para ser confiable

• ✅ Plan → revisión → aplicación → verificación. Las acciones masivas se congelan en un plan que puedes leer antes de que ocurra cualquier cosa; el resultado se confirma contra el propio almacén de Mail después — nunca se asume.
• 🗑️ Nada se borra jamás. "Eliminar" archiva en la Papelera de Mail, y los planes destructivos tienen su propia puerta separada y limitada.
• 👓 Modo de correo solo lectura. Establece EMAIL_MCP_READ_ONLY=1 y solo existen las 11 herramientas de correo no mutantes en la sesión. La búsqueda puede mantener su índice de cuerpo local, y la recuperación de adjuntos escribe el archivo solicitado en el directorio temporal configurado.
• 💾 Cola de programación a prueba de fallos. Las actualizaciones del manifiesto se vacían y se reemplazan atómicamente, por lo que una reescritura interrumpida conserva el último registro válido. Si un archivo se daña de forma independiente, los diagnósticos lo nombran en lugar de afirmar que la cola está vacía, mientras los mensajes programados saludables siguen moviéndose.
• 🧾 Registro de actividad local de mejor esfuerzo. Envíos, programaciones, cancelaciones y ejecuciones de clasificación se registran sin que un registro no escribible bloquee el correo. Para la conciliación, el mensaje en sí, su Message-ID y su registro programado siguen siendo autoritativos.
• 🔒 Sin retransmisión de correo de terceros. El contenido del correo permanece local excepto por el correo que envías y el acceso opcional a tu propio proveedor para el relleno de cuerpos de Exchange/IMAP, borradores y programación en el servidor. Las contraseñas SMTP permanecen en el Llavero de macOS o en 1Password; los tokens OAuth de Microsoft viven en una caché privada 0600 bajo ~/.email-mcp/graph/.
• 📜 Un contrato escrito. Desde v1.0, las formas, códigos de error y límites de cada herramienta evolucionan de forma aditiva, mantenidos por más de 800 pruebas automatizadas.
• 🤝 Claro para cada cliente MCP. Las 21 herramientas identifican qué hacen, explican cada entrada y declaran si leen, cambian o pueden eliminar datos. Los clientes más nuevos reciben resultados estructurados; los más antiguos mantienen el mismo texto JSON. Se prueban tanto la línea mantenida MCP 1.x como la actual MCP 2.x.
• 🧱 Diseñado para evolucionar sin romper tu flujo de trabajo. Las reglas de correo están aisladas de MCP, Mail.app, Exchange, entrega y almacenamiento local. Los cambios de proveedor o SDK permanecen en el borde mientras el contrato de 21 herramientas permanece estable. Las reglas de dependencia se aplican en CI y se explican en la guía de arquitectura.
• 📦 Versiones que puedes verificar. Cada versión etiquetada se compila e instala en un entorno limpio antes de publicarse. GitHub incluye la rueda, el archivo fuente, las sumas de verificación SHA-256 y la procedencia de compilación firmada—no solo el código fuente.
• 🩺 Autodiagnóstico. apple-mail-mcp status ofrece una pantalla legible de preparación, programación y recuperación. apple-mail-mcp doctor proporciona el detalle de diagnóstico completo y una corrección exacta para cualquier cosa en rojo.

🚀 Inicio rápido

1. Concede Acceso Total al Disco a tu aplicación de terminal (Configuración del Sistema → Privacidad y Seguridad → Acceso Total al Disco), luego cierra y vuelve a abrir la terminal. Este es el único interruptor manual de Apple — no hay ventana emergente para ello.

2. Instala y configura:

   uvx apple-mailbox-mcp setup     # or: pipx install apple-mailbox-mcp
   # or via Homebrew:
   brew install parasxos/tap/apple-mail-mcp && apple-mail-mcp setup
   

3. Regístrate con tu cliente — una línea para Claude Code:

   claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp
   

   o el mismo bloque JSON para Claude Desktop / Cursor / VS Code (claude_desktop_config.json / .cursor/mcp.json / .vscode/mcp.json):

   {
     "mcpServers": {
       "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] }
     }
   }
   

4. Verifica: uvx apple-mailbox-mcp status imprime una pantalla de preparación — o simplemente pide a tu cliente que ejecute la herramienta doctor; cada línea en rojo viene con su corrección exacta. La primera compilación del índice de cuerpo en un buzón grande se ejecuta en segundo plano y puede tardar unos minutos; la búsqueda funciona de inmediato y se completa a medida que se llena el índice.

Antes de ejecutar setup, concede a tu aplicación de terminal Acceso Total al Disco (Configuración del Sistema → Privacidad y Seguridad → Acceso Total al Disco) — así es como la lectura se mantiene rápida y local. No hay ventana emergente para esto; es el único interruptor manual de Apple, y setup te lleva al panel exacto si lo encuentra faltante.

setup pregunta todo en palabras simples (Enter vacío acepta la respuesta recomendada), ofrece una identidad de envío, compila el índice de búsqueda de cuerpo, verifica que la actualización nocturna realmente se ejecute y termina imprimiendo el bloque único que pegas en tu cliente MCP:

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

La configuración termina con un veredicto claro de listo o pasos de recuperación numerados. Concede Automatización → Mail cuando la clasificación lo solicite por primera vez. Verifica la instalación, el próximo mensaje programado y los envíos programados fallidos en cualquier momento con apple-mail-mcp status; usa apple-mail-mcp doctor para el detalle técnico completo.

💡 ¿Nuevo en la terminal? Tres cosas que parecen mal y no lo están: brew install pipx quiere un y escrito (Enter solo se rechaza); pipx ensurepath puede imprimir un ⚠️ — la línea "pipx está listo para funcionar" después es el veredicto; y después de ensurepath, cierra y vuelve a abrir la terminal una vez para que apple-mail-mcp se encuentre.

🔌 Funciona con

Cada cliente a continuación habla MCP stdio; el comando es siempre uvx apple-mailbox-mcp.

Claude Code

claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }

Cursor

Añade el mismo bloque a ~/.cursor/mcp.json (o por proyecto .cursor/mcp.json).

VS Code (Copilot MCP)

Añade el mismo bloque bajo "servers" en .vscode/mcp.json.

Codex CLI

# ~/.codex/config.toml
[mcp_servers.apple-mail]
command = "uvx"
args = ["apple-mailbox-mcp"]

Cualquier cliente MCP stdio

Apúntalo a uvx apple-mailbox-mcp. El contrato de cable es solo aditivo desde v1.0.

🔧 Solución de problemas

Síntoma	Corrección
El cliente dice que el servidor no pudo iniciar, pero uvx apple-mailbox-mcp funciona en tu terminal	Las aplicaciones GUI no heredan el PATH de tu shell. Usa la ruta absoluta: "command": "/opt/homebrew/bin/uvx" (encuentra la tuya con which uvx).
database is locked o resultados vacíos	Falta Acceso Total al Disco para la aplicación que inicia el servidor (el cliente, no la terminal). Concédelo, luego cierra y vuelve a abrir esa aplicación por completo.
La búsqueda encuentra correo reciente pero no cuerpos de correo antiguo	El índice de cuerpo aún se está compilando — la primera compilación en un buzón de 100k+ tarda minutos. status muestra el progreso.
El envío falla con transport_unavailable	Ejecuta doctor: nombra la vía que falla (elemento del Llavero faltante, socket SSH frío, host SMTP inalcanzable) e imprime la corrección exacta.
La clasificación no hace nada la primera vez	Concede Automatización → Mail cuando macOS lo solicite; la ventana aparece en el primer uso, no en la instalación.

🧰 Las 21 herramientas

Grupo	Herramientas
🔍 Lectura (8)	search_emails (búsqueda de cuerpo completo) · get_email · get_emails_batch · get_thread · list_mailboxes · list_recent · get_attachment · refresh_mail
✉️ Envío (6)	send_email · reply_email (con hilo, citado) · create_draft · schedule_email · list_scheduled · cancel_scheduled
🗂️ Clasificación (5)	triage_plan · triage_plan_delete · triage_apply · mailbox_create · mailbox_delete
🩺 Meta (2)	doctor (diagnóstico completo con cadenas de corrección) · audit (el registro local)

Adjuntos en ambas direcciones, con presupuesto de tamaño. Las respuestas se enhebran correctamente en cada cliente. La programación sobrevive al sueño — un mensaje que vence mientras la tapa estaba cerrada sale en el primer tick después del despertar, o exactamente a tiempo vía Exchange.

🎭 Tus direcciones, tus vías

La dirección De: decide cómo viaja el correo. ~/.email-mcp/identities.toml:

default = "work"

[work]                    # sent through a host you already trust, over SSH
from_addr = "you@example.org"
driver    = "ssh_sendmail"
host      = "bastion.example.org"   # any login host you already SSH to

[gmail]                   # classic SMTP — the app password stays in 1Password
from_addr = "you@gmail.com"
driver    = "smtp"
host      = "smtp.gmail.com"
op        = "op://Personal/gmail app password/password"

Las identidades de Exchange pueden añadir un inicio de sesión para desbloquear los extras: borradores archivados en tu carpeta real de Borradores y envíos programados ejecutados por el propio servidor — tapa cerrada, Mac dormido. setup lo ofrece en una sola pregunta simple. La lectura no necesita configuración de envío en absoluto.

---