✉️ apple-mail-mcp

Tu Apple Mail, totalmente operativo por agentes.

Se ejecuta localmente en tu Mac. Abre el almacén de Mail en modo solo lectura, devuelve solo lo que un cliente pide y envía solo cuando el cliente llama explícitamente a la herramienta de envío. Sin relé de terceros, sin copia en la nube de tu correo.

Usa Claude, Codex, Cursor, VS Code o cualquier cliente MCP local para buscar, leer, clasificar y enviar correo a través de Apple Mail: tu bandeja de entrada se convierte en algo que puedes preguntar, buscar y delegar — encuentra cualquier cosa en segundos, archiva cientos de mensajes mediante un plan revisado, envía correo pulido con la identidad correcta y deja que Exchange entregue mensajes programados incluso mientras tu Mac está dormido.

✨ Lo que puedes hacer

🔍 Pregunta a tu bandeja de entrada. "¿Qué me envió Stefan sobre el memo la semana pasada?" La búsqueda corre 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 hojea 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 de tu propio buzón en el servidor. Las consultas que no devolvían nada devuelven veinte.

🎭 Envía como el tú correcto. El correo de trabajo por el carril de trabajo, el 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 scriptable. 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 comprobar antes de tocarlo y el resultado se verifica después contra los propios registros de Mail. Eliminar significa la 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.

Related MCP server: apple-mail-readonly-mcp

⚡ 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.

🛡️ Construido para ser confiable

• ✅ Plan → revisar → aplicar → verificar. Las acciones masivas se congelan en un plan que puedes leer antes de que ocurra nada; el resultado se confirma después contra el propio almacén de Mail, 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 de 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 del manifiesto se vacían y se reemplazan atómicamente, por lo que una reescritura interrumpida mantiene 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 libro de actividades 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 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 por 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 lo que 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 MCP 1.x mantenida como la MCP 2.x actual.

• 🧱 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.

• 📦 Lanzamientos que puedes verificar. Cada lanzamiento etiquetado se compila e instala en un entorno limpio antes de publicarse. GitHub incluye el wheel, 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 (Ajustes del Sistema → Privacidad y Seguridad → Acceso Total al Disco), luego sal 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

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 roja 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 (Ajustes del Sistema → Privacidad y Seguridad → Acceso Total al Disco) — así la lectura sigue siendo 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 claras (Enter vacío acepta la respuesta recomendada), ofrece una identidad de envío, construye el índice de búsqueda de cuerpo, verifica que la actualización nocturna realmente se ejecute y termina imprimiendo el bloque que pegas en tu cliente MCP:

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

El setup termina con un veredicto claro de listo o pasos de recuperación numerados. Concede Automatización → Mail cuando la clasificación lo pida por primera vez. Comprueba 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 una y tecleada (Enter solo se rechaza); pipx ensurepath puede imprimir un ⚠️ — la línea "pipx is ready to go!" después es el veredicto; y después de ensurepath, cierra y vuelve a abrir la terminal una vez para que se encuentre apple-mail-mcp.

🔧 Solución de problemas

🧰 Las 21 herramientas

Adjuntos en ambos sentidos, con presupuesto de tamaño. Las respuestas se encadenan correctamente en todos los clientes. La programación sobrevive al sueño — un mensaje que debía enviarse con la tapa cerrada sale en el primer tic tras despertar, o exactamente a tiempo mediante Exchange.

🎭 Tus direcciones, tus carriles

La dirección From: 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 único inicio de sesión para desbloquear los extras: borradores guardados en tu carpeta Drafts real, y envíos programados ejecutados por el propio servidor — con la tapa cerrada, el Mac dormido. setup lo ofrece en una única pregunta sencilla. Leer no requiere ninguna configuración de envío.

21 herramientas · 849 pruebas · contrato de protocolo aditivo desde v1.0 Calibrado en vivo de extremo a extremo sobre un almacén de 305k mensajes.

Construido para un Mac — y para cualquiera cuyo Mac ejecute Mail.app.