Apple Productivity MCP

Servidor MCP local gratuito para Apple Mail, Calendar y Reminders en macOS.

Documentación

Apple Productivity MCP

Un servidor local Model Context Protocol (MCP) bajo demanda que brinda a Claude Code y Codex acceso controlado a Apple Mail, Calendar y Reminders en macOS.

Utiliza la interfaz de automatización integrada de Apple a través de /usr/bin/osascript. El transporte MCP es stdio: tu cliente MCP inicia el proceso cuando se conecta y lo detiene cuando la sesión lo libera. No hay puerto de escucha, servicio en segundo plano ni servidor MCP alojado en la nube.

Características

App	Leer y descubrir	Acciones
Mail	Listar cuentas y buzones, listar metadatos de mensajes, leer un mensaje	Enviar, marcar como leído/no leído, marcar/desmarcar, mover, eliminar
Calendar	Listar calendarios, listar eventos en un rango de tiempo	Crear, actualizar, eliminar
Reminders	Listar listas de recordatorios, listar recordatorios	Crear, actualizar, completar, eliminar

El servidor publica anotaciones de herramientas MCP para comportamiento de solo lectura, idempotente, destructivo y de mundo abierto. Estas anotaciones ayudan a los clientes compatibles a aplicar políticas de aprobación adecuadas; no sustituyen la revisión de una acción de escritura antes de aprobarla.

Requisitos

macOS con Mail, Calendar y Reminders
Node.js 20 o más reciente
Claude Code, Codex CLI/app/extensión de IDE, u otro cliente MCP compatible con stdio
Permiso para que el cliente que inicia el servidor automatice las aplicaciones Apple relevantes

Instalar desde npm

Este es el método de instalación recomendado. No se requiere clonar el repositorio ni instalar un paquete global. npx descarga y almacena en caché el paquete publicado, y el cliente MCP lo inicia como un proceso hijo local stdio cuando una sesión se conecta.

Confirma que Node.js y npx estén disponibles:

node --version
npx --version

Los ejemplos usan @latest para que las nuevas sesiones resuelvan la versión publicada más reciente. Reemplázalo con una versión explícita como @2.1.1 cuando quieras una instalación reproducible y fijada.

Claude Code

Agrega el servidor a tu configuración de usuario para que esté disponible en cada proyecto:

claude mcp add --transport stdio --scope user apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest

Verifica el registro:

claude mcp get apple-productivity-local
claude mcp list

Inicia una nueva sesión de Claude Code después de agregar el servidor. Si el nombre ya está registrado, elimínalo con claude mcp remove apple-productivity-local --scope user y ejecuta el comando de agregar nuevamente.

App Codex, CLI y extensión de IDE

Agrega el servidor a la configuración de usuario de Codex:

codex mcp add apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest

Verifica el registro:

codex mcp get apple-productivity-local
codex mcp list

La app Codex, CLI y extensión de IDE comparten esta configuración MCP en el mismo Mac. Inicia una nueva sesión después de la instalación; reinicia una app o extensión de IDE ya abierta para que recargue la configuración. En la CLI de Codex, /mcp muestra los servidores activos.

Si el nombre ya está registrado, ejecuta codex mcp remove apple-productivity-local y agrégalo nuevamente.

Otros clientes MCP locales

Usa estos valores en cualquier cliente que pueda iniciar un servidor MCP stdio local:

Configuración	Valor
Nombre	`apple-productivity-local`
Transporte	`stdio`
Comando	`npx`
Argumentos	`-y`, `@gambadio/apple-productivity-mcp@latest`
Variables de entorno	Ninguna
Directorio de trabajo	Ninguno requerido

Los clientes que aceptan la forma común de configuración JSON pueden usar:

{
  "mcpServers": {
    "apple-productivity-local": {
      "command": "npx",
      "args": [
        "-y",
        "@gambadio/apple-productivity-mcp@latest"
      ]
    }
  }
}

La clave de configuración externa y la ubicación del archivo varían según el cliente. En una pantalla de configuración gráfica, selecciona STDIO e ingresa el comando y los argumentos de la tabla. Este patrón se aplica a clientes MCP locales como Claude Desktop, Cursor, Windsurf, Cline y editores compatibles; consulta la documentación del cliente para saber dónde almacena la configuración MCP.

Si un cliente de escritorio no puede encontrar npx, ejecuta esto en Terminal:

command -v npx

Luego reemplaza "command": "npx" con la ruta absoluta devuelta, por ejemplo "command": "/usr/local/bin/npx".

Reinicia el cliente o abre una nueva sesión después de cambiar su configuración MCP. Los clientes que solo admiten servidores HTTP remotos no pueden ejecutar este MCP directamente porque Apple Productivity MCP usa intencionalmente stdio local y automatización de macOS.

No necesitas ejecutar npm start, instalar el paquete globalmente, mantener una terminal abierta, configurar una clave API ni exponer un puerto de red.

Instalar desde el código fuente

Usa un checkout del código fuente cuando desarrolles el servidor o cuando quieras ejecutar un commit específico de Git.

Clona el repositorio e instala sus dependencias bloqueadas:

git clone https://github.com/gambadio/apple-productivity-mcp.git
cd apple-productivity-mcp
npm ci

Captura las rutas absolutas que los clientes MCP deben almacenar:

APPLE_MCP_NODE="$(command -v node)"
APPLE_MCP_SERVER="$(pwd)/src/index.js"

Se admiten rutas con espacios. Mantén las comillas en los comandos a continuación.

Claude Code con un checkout del código fuente

Instala el servidor para tu cuenta de usuario:

claude mcp add --transport stdio --scope user apple-productivity-local -- \
  "$APPLE_MCP_NODE" "$APPLE_MCP_SERVER"

Verifica el registro:

claude mcp get apple-productivity-local
claude mcp list

Codex con un checkout del código fuente

Instala el mismo servidor stdio local en Codex:

codex mcp add apple-productivity-local -- \
  "$APPLE_MCP_NODE" "$APPLE_MCP_SERVER"

Verifica el registro:

codex mcp get apple-productivity-local
codex mcp list

Codex almacena esto en su configuración de usuario, compartida por la app Codex, CLI y extensión de IDE en el mismo host. Inicia una nueva sesión después de la instalación. Si una app de escritorio o extensión de IDE ya estaba abierta, reiníciala para que recargue la configuración MCP.

No necesitas ejecutar npm start ni mantener una terminal abierta. El cliente MCP inicia el checkout del código fuente como un proceso hijo cuando establece la conexión MCP.

Otorgar permiso de macOS

La primera llamada real de herramienta para cada app de Apple puede activar un aviso de Automatización de macOS. Aprueba el acceso para la aplicación que inició el servidor MCP, como Terminal, iTerm, Claude Code, Codex o tu IDE.

Si denegaste un aviso o no aparece ningún aviso:

Abre Configuración del Sistema → Privacidad y Seguridad → Automatización.
Encuentra la aplicación que inicia tu cliente MCP.
Habilita Mail, Calendar y Reminders según sea necesario.
Reinicia el cliente MCP e inténtalo nuevamente.

Pruébalo

Comienza con las herramientas de descubrimiento para que el cliente aprenda los nombres locales exactos configurados en tu Mac:

"Lista mis cuentas y buzones de Apple Mail."
"Lista mis calendarios de Apple editables."
"Lista mis listas de Apple Reminders."
"Muestra eventos de todos los calendarios para mañana."
"Muestra mis recordatorios incompletos."

Mail usa por defecto el nombre de cuenta iCloud y el buzón INBOX cuando un llamador no proporciona nombres. Usa apple_mail_list_accounts primero si tu configuración usa nombres diferentes.

Referencia de herramientas

Mail

apple_mail_list_accounts — lista nombres de cuentas, direcciones de remitente y buzones
apple_mail_list — lista metadatos de mensajes sin leer cuerpos
apple_mail_get — lee un mensaje, incluido su cuerpo
apple_mail_send — envía un mensaje inmediatamente
apple_mail_update_status — marca como leído/no leído o marca/desmarca
apple_mail_move — mueve un mensaje a otro buzón en la misma cuenta
apple_mail_delete — elimina un mensaje usando el comportamiento de Mail.app

Calendar

apple_calendar_list_calendars — lista nombres de calendarios y estado de escritura
apple_calendar_list_events — lista eventos superpuestos en un rango de tiempo ISO 8601
apple_calendar_create_event — crea un evento
apple_calendar_update_event — actualiza un evento por UID
apple_calendar_delete_event — elimina un evento por UID

Reminders

apple_reminders_list_lists — lista nombres e IDs de listas de recordatorios
apple_reminders_list — lista recordatorios, opcionalmente incluyendo elementos completados
apple_reminders_create — crea un recordatorio
apple_reminders_update — actualiza un recordatorio por ID
apple_reminders_complete — marca un recordatorio como completado
apple_reminders_delete — elimina un recordatorio por ID

Privacidad y seguridad

El servidor MCP en sí no tiene listener de red y no almacena credenciales ni datos de Apple.
Las entradas se pasan a osascript como argumentos JSON en lugar de interpolarse en código fuente JXA ejecutable.
Los cambios en Mail, Calendar y Reminders pueden sincronizarse a través de iCloud, CalDAV, Exchange u otro proveedor configurado.
"MCP local" describe dónde se ejecuta el servidor. El contenido devuelto a Claude Code o Codex se convierte en parte de esa sesión de modelo activa y puede procesarse según los controles de datos de ese producto.
Enviar, mover, actualizar, completar y eliminar son acciones reales. Revisa las solicitudes de herramientas de escritura antes de aprobarlas.

Actualizar

Los registros que usan el comando npm con @latest resuelven la versión publicada más reciente cuando se inicia un nuevo proceso MCP. Inicia una nueva sesión de Claude Code o Codex después de un lanzamiento. Fija una versión explícita si las actualizaciones automáticas no son deseables.

Para un checkout del código fuente, actualiza en el lugar para que la ruta absoluta almacenada siga siendo válida:

cd /absolute/path/to/apple-productivity-mcp
git pull --ff-only
npm ci
npm test

Eliminar

claude mcp remove apple-productivity-local --scope user
codex mcp remove apple-productivity-local

Eliminar el registro no limpia la caché de npm, no elimina un repositorio clonado ni cambia los datos de Apple.

Desarrollo y verificación

Instala dependencias y ejecuta la suite de pruebas aislada:

npm ci
npm test
npm audit --omit=dev

Ejecuta las pruebas de integración en vivo de solo lectura después de otorgar el permiso de Automatización:

npm run test:integration

La ejecución de pruebas predeterminada omite las pruebas de integración en vivo porque acceden a las aplicaciones Apple instaladas del usuario.

Solución de problemas

`Apple automation unavailable` o un error de autorización

Revisa Configuración del Sistema → Privacidad y Seguridad → Automatización, habilita la app de Apple afectada para el proceso que inicia tu cliente MCP y luego reinicia el cliente.

`Mail account not found`, `Calendar not found` o `Reminder list not found`

Ejecuta la herramienta de descubrimiento correspondiente y usa el nombre devuelto exacto. Los nombres son locales a tu configuración de macOS y pueden diferir según el idioma o el proveedor.

`spawn ... ENOENT`

Para una instalación npm, ejecuta command -v npx y usa la ruta absoluta devuelta como el comando configurado. Para un checkout del código fuente, elimina y vuelve a agregar el registro MCP usando valores nuevos de command -v node y pwd.

El paquete npm no se puede descargar

Confirma que el paquete público sea accesible y que el cliente tenga acceso a internet para la primera instalación:

npm view @gambadio/apple-productivity-mcp version

Después de que el paquete se haya descargado, npm puede reutilizar su caché local para esa versión.

El servidor está registrado pero las herramientas no aparecen

Ejecuta los comandos mcp get/mcp list del cliente y luego inicia una nueva sesión. Reinicia una app de escritorio o extensión de IDE ya abierta después de cambiar la configuración MCP.

Licencia

MIT

Apple Productivity MCP

Documentación