Apple Mail

uvx apple-mailbox-mcp setup

✨ Lo que puedes hacer

🔍 Haz preguntas a tu buzón. "¿Qué me envió María 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 estándar que se renderiza en todas partes, incluido Outlook (la ruta de composición de AppleScript que llega en blanco a Outlook es la razón por la que existe este proyecto).

⏰ Programa como "Enviar más tarde", pero scriptable. Un mensaje programado se congela por completo — adjuntos, identidad, texto exacto y, desde la versión 1.8.2, los encabezados de hilo, para que una respuesta programada aterrice en la conversación que responde. 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, listo para abrir en Outlook u OWA — creado, nunca autoenviado.

⚡ Por qué es diferente

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

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 nada; 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.
• 💾 Una cola programada a prueba de fallos. Las actualizaciones de 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 que los mensajes programados saludables siguen moviéndose.
• 🧾 Un registro de actividad local de mejor esfuerzo. Los 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 relé 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 de OAuth de Microsoft viven en una caché privada 0600 bajo ~/.email-mcp/graph/.
• 📜 Un contrato escrito. Desde la v1.0, las formas, códigos de error y límites de cada herramienta evolucionan de forma aditiva, respaldados por más de 800 pruebas automatizadas.
• 🤝 Claro para cada cliente MCP. Las 21 herramientas identifican lo que hacen, explican cada entrada y declaran si leen, cambian o pueden eliminar datos. Los clientes más nuevos reciben resultados estructurados; los clientes más antiguos mantienen el mismo texto JSON. Se prueban MCP SDK 2.2 y versiones 2.x más nuevas, con soporte para clientes más antiguos.
• 🧱 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 se mantiene 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. Otorga Acceso Total al Disco a tu aplicación de terminal (Configuración del Sistema → Privacidad y Seguridad → Acceso Total al Disco), luego cierra y reabre 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 tomar unos minutos; la búsqueda funciona de inmediato y se completa a medida que se llena el índice.

Antes de ejecutar setup, otorga 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 único bloque 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. Otorga 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!" después es el veredicto; y después de ensurepath, cierra y reabre la terminal una vez para que se encuentre apple-mail-mcp.

🔌 Funciona con

Cada cliente a continuación habla stdio MCP; 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

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor

Agrega el mismo bloque a ~/.cursor/mcp.json (o por proyecto .cursor/mcp.json).

VS Code (Copilot MCP)

Agrega 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 stdio MCP

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

🔧 Solución de problemas

🧰 Las 21 herramientas

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 programado 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 agregar 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. Leer no necesita configuración de envío en absoluto.