Cupertino

Pon a trabajar a tu agente en tus apps de Apple de todos los días.

Servidores MCP para las apps de Apple que ya tienes en tu Mac, y la app firmada que les concede sus permisos una sola vez en lugar de una por cada una — para cualquier agente que hable MCP, no para un solo host.

No oficial. No está afiliado a Apple. Estos controlan las apps que ya están en tu Mac.

En uso

Fíjate en cómo escribo en mi bandeja de entrada del trabajo y redacta esta respuesta con el mismo tono.

Reúne todo lo relacionado con el lanzamiento de Atlas de mi correo, mis notas y mi calendario. ¿Qué les sigo debiendo a los demás?

Convierte los elementos de acción del hilo de ayer con el cliente en recordatorios, para el viernes.

Cada una de esas frases lleva una restricción — una cuenta, un límite de fecha, un filtro. Esa es la parte que la vía ingenua de osascript responde en 74 segundos o responde mal, y la razón por la que un servidor se gana su lugar: guarda lo que el modelo tendría que volver a deducir en cada sesión. Las mediciones están en docs/verify.md; lo que cuestan las alternativas está en docs/alternatives.md.

La última necesita la puerta de escritura abierta en Recordatorios. Las escrituras están desactivadas por superficie hasta que las actives, y el interruptor decide si las herramientas de mutación se registran siquiera — un agente con las escrituras desactivadas no puede ver que existen.

Related MCP server: apple-mcp

Superficies

Cada superficie es su propio servidor y su propio paquete npm, de modo que un host carga solo las herramientas que quiere. Comparten un mismo bundle y una misma concesión de Acceso total al disco, que es la razón de que vivan juntos — ver docs/distribution.md.

Inicio rápido

Cada servidor está en npm y se ejecuta directamente desde npx — para Claude Code, un .mcp.json junto a tu proyecto:

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-mail"]
    },
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@mgcrea/mcp-apple-notes"]
    }
  }
}

Los paquetes son MIT y no necesitan clave de licencia. Lo que sí necesitan es un permiso, y en npm se lo concedes a quien los lanza — tu editor, tu terminal — que es el intercambio que la Cupertino.app firmada existe para evitar: una sola concesión de Acceso total al disco en manos de un binario notarizado, en lugar de una por host. Ver docs/licensing.md.

O ejecútalos desde el código fuente:

git clone https://github.com/mgcrea/mcp-cupertino.git
cd mcp-cupertino
pnpm install
pnpm build

y luego apunta tu host a packages/<surface>/dist/cli.js por ruta absoluta.

Las escrituras están desactivadas a menos que las pidas — ver Configuración.

Si los ejecutas a través de la app de la barra de menús, en cambio, cada servidor pasa por el puente, de modo que el Acceso total al disco se concede a Cupertino y no al editor que haya lanzado el servidor:

make run      # build Cupertino.app, point it at packages/*/dist, launch it
make smoke    # handshake every server through the bridge

El .mcp.json incluido en el repositorio está configurado para esa ruta. make por sí solo lista todos los objetivos.

Observa los distintos nombres de servidor. Configurado a mano como arriba, un servidor se llama apple-mail y se ejecuta bajo la concesión que tenga su proceso host. Configurado por Cupertino se llama cupertino-mail, porque esa entrada apunta al puente de la app y se ejecuta bajo la concesión de la app. Dos nombres para dos despliegues, y puedes tener ambos. La app solo toca sus propias claves cupertino-* — una entrada apple-mail que pertenezca a otro servidor se deja intacta.

Cupertino es configuración de la máquina, no una dependencia del proyecto, así que pertenece a una configuración por usuario: un archivo para cada uno de Claude Desktop, Cursor, LM Studio y Windsurf, y --scope user para las CLI, que es lo que usan los comandos copiables de la app. Deliberadamente no --scope project, que escribe un .mcp.json pensado para ser commiteado — esa entrada es una ruta absoluta a un bundle en un Mac concreto, respaldada por la concesión de Acceso total al disco de una persona, y sería inútil para un compañero de equipo y poco prudente ofrecérsela.

Qué clientes reciben una escritura y cuáles reciben un comando no es cuestión de popularidad. La app fusiona en una configuración solo cuando es JSON estricto con servidores bajo mcpServers; el de Visual Studio Code es JSONC y el de Codex es TOML, y re-serializar cualquiera de los dos borraría los comentarios de un archivo mantenido a mano. El ~/.claude.json de Claude Code es JSON estricto, pero contiene credenciales y las sesiones en ejecución escriben en él de forma concurrente, así que una lectura-modificación-escritura desde la barra de menús podría descartar el cambio de otra persona. Esos tres reciben una línea para pegar. ChatGPT está ausente por completo: acepta conectores HTTP remotos y no puede lanzar un servidor stdio local en absoluto.

El .mcp.json propio de este repositorio es la excepción, y nombra a sus servidores cupertino-*-dev a propósito: apunta a apps/apple/.build, así que trabajar en la app significa tener la compilación de desarrollo y la instalada una al lado de la otra. Claude Code reporta los servidores del mismo nombre en dos ámbitos como un conflicto en lugar de elegir uno, así que el sufijo es lo que mantiene ambos utilizables.

Cupertino.app necesita macOS 26 o posterior — su icono es un bundle de Icon Composer, que nada más antiguo puede renderizar. Los servidores en sí son Node puro y no tienen ese requisito mínimo; solo la app de la barra de menús lo tiene.

Permisos

Dos concesiones separadas de macOS, y recaen sobre el proceso que haya lanzado el servidor — tu editor, tu terminal o Cupertino — nunca sobre Mail, Notas o Recordatorios en sí.

Ajustes del Sistema → Privacidad y seguridad → Acceso total al disco → añade la app que lanza, y reiníciala. Concedérselo a Mail.app no hace nada; el lector necesita el permiso, no Mail.

Qué funciona sin Acceso total al disco:

Las herramientas que necesitan el índice no desaparecen cuando falta — la lista de herramientas es una función pura de allowWrites y nada más, porque los clientes MCP la guardan en caché. Devuelven un resultado estructurado degraded que nombra lo que falta. apple_mail_diagnostics / apple_notes_diagnostics informan de qué carril está activo y de cómo conceder lo que falta.

Herramientas

Las herramientas de lectura siempre están registradas. Las de escritura son invisibles a menos que las escrituras estén activadas — no solo rechazadas.

Mail

Notas

Recordatorios

Calendario

list_events expande los eventos periódicos, de modo que una reunión semanal se devuelve una vez por semana. Cada resultado incluye la ventana que se sabe que cubre la expansión y establece truncated cuando un rango la supera en lugar de devolver menos resultados: una lista corta de eventos es indistinguible de una tarde libre.

Contactos

resolve_handles convierte números de teléfono y direcciones de correo electrónico en nombres, que es lo que hace legible la superficie de Messages. Lee status en cada resultado en lugar de asumir que se devolvió un nombre: unknown es habitual y no es un error, y ambiguous significa que dos contactos comparten el número, por lo que no se devuelve ningún nombre en lugar de una suposición.

No hay herramienta de borrado. El diccionario de scripting de Contacts no tiene ningún comando de borrado de ningún tipo, y las escrituras pasan por Apple Events en todas las superficies porque el almacén es de solo lectura por política. Consulta docs/contacts.md.

Mensajes

Una sola herramienta de escritura, porque el diccionario tiene un único comando utilizable. sdef lista send, login y logout; los otros dos cerrarían la sesión del usuario de iMessage en todos sus dispositivos. No hay ningún verbo de editar, borrar, marcar como leído o reaccionar que exponer.

Esta es la única superficie donde Apple Events es un carril de escritura y nada más: cualquier lectura a través de él falla, así que con APPLE_MESSAGES_ALLOW_WRITES desactivado nunca se envía ningún Apple Event y nunca se solicita ningún permiso de Automation.

send_message prefiere un chatRef de list_chats antes que un identificador bruto, porque Messages se niega a enumerar participantes para un script: una conversación existente es el único destino al que se puede dirigir de forma fiable. Apple Events no devuelve ningún identificador de lo que envió, así que el resultado se concilia contra chat.db — reconciliation: "matched" lleva una referencia de mensaje real, y "pending" significa que Messages aceptó el envío pero aún no ha escrito la fila. Pendiente no es un fallo, y reintentarlo envía el mensaje dos veces.

Alrededor del 3% de los mensajes de toda la historia conservan su texto solo en un blob NSArchiver archivado al que SQL no puede acceder, y Apple dejó de escribir la columna de texto plano a principios de 2026, así que para cualquier cosa reciente es ~100%. Este servidor los decodifica; textSource en cada resultado indica qué carril respondió. Consulta docs/messages.md.

Safari

De solo lectura, y la columna de escritura está vacía a propósito. Abrir una URL o añadir a la Lista de lectura es un Apple Event que navega en un navegador real y visible, y ninguna escritura en esta superficie se probó jamás.

list_tabs es la única herramienta de todo el paquete que funciona sin Acceso a disco completo: en su lugar necesita un permiso de Automation, y Safari tiene que estar en ejecución. Que el campo history de una pestaña sea nulo significa no encontrado en el historial, nunca "no visitada": solo alrededor del 55% de las pestañas abiertas coinciden con una fila del historial, porque las redirecciones, los parámetros de sesión y las páginas nunca confirmadas en el historial producen una URL que simplemente no está.

No existe la herramienta do JavaScript. Ese verbo necesita "Permitir JavaScript desde Apple Events", una opción del menú de desarrollo de Safari que no es un permiso de TCC y cuyo propio estado no se puede leer de forma fiable. Publicarlo significaría informar de una superficie sana cuya capacidad más potente falla silenciosamente. Consulta docs/safari.md.

Todos los nombres llevan el prefijo apple_mail_ / apple_notes_ / apple_reminders_ / apple_calendar_ / apple_contacts_ / apple_messages_ / apple_safari_.

Configuración

Solo variables de entorno: estos servidores no guardan ningún secreto propio, así que no hay archivo de configuración. El prefijo es APPLE_MAIL_, APPLE_NOTES_, APPLE_REMINDERS_, APPLE_CALENDAR_, APPLE_CONTACTS_, APPLE_MESSAGES_ o APPLE_SAFARI_.

allowWrites controla la mutación, pero en Mail el mayor radio de daño es leer un archivo completo: para eso sirve *_ACCOUNTS, y se aplica en un único lugar para que ninguna ruta de consulta pueda esquivarlo. Mail también acepta *_ROOT, *_ENVELOPE_INDEX, *_DEGRADED_MAX_MESSAGES, *_BODY_MAX_BYTES, *_BODY_SCAN_MAX, *_BODY_SCAN_BYTES y *_MAILBOX_CACHE_TTL_MS; consulta packages/mail/src/config.ts.

La app

La barra de menús es toda la superficie de Cupertino: no hay icono en el Dock ni ventana principal.

La ventana de Actividad registra solo los nombres de las herramientas, nunca argumentos, contenidos de mensajes ni resultados. Es la respuesta a "¿qué acaba de hacer el asistente con mi correo?" y la razón por la que los servidores se ejecutan bajo una app visible en lugar de dentro del editor que los haya lanzado.

Las escrituras están desactivadas por superficie hasta que las actives, y el interruptor decide si las herramientas de mutación se registran siquiera: un asistente con las escrituras desactivadas no puede ver que existen.

Por qué una sola app

El Acceso a disco completo es un permiso indivisible de todo el disco. Concederlo por superficie no aporta ningún aislamiento y cuesta una visita a Ajustes del Sistema cada vez, así que cada superficie se distribuye dentro de una única app firmada y notarizada llamada Cupertino. docs/distribution.md también documenta por qué la Mac App Store no puede alojar nada de esto, para que no se vuelva a plantear la cuestión.

Pero el permiso no es lo único que posee la app, ni es la única razón para ejecutar los servidores bajo ella en lugar de bajo un editor:

docs/alternatives.md es la versión honesta de esa lista: qué más lee Apple Mail para un asistente y en qué aspectos esas herramientas van por delante.

Documentación

Trabajando en ello

pnpm build          # every package
pnpm test           # every package
pnpm typecheck
pnpm lint
pnpm format

El sitio de marketing es su propio espacio de trabajo y se despliega a mano:

pnpm --filter @mgcrea/cupertino-website dev     # astro dev
pnpm --filter @mgcrea/cupertino-website build   # static build

Se construye desde el lienzo de diseño en .idea/design/, y lee sus recuentos de herramientas de packages/*/src/tools/ en lugar de este archivo — ver apps/website.

La mitad Swift es xcodebuild, nombrada por el Makefile en lugar de estar envuelta por él:

make app            # build Cupertino.app (Debug)
make run            # build, point at packages/*/dist, launch
make smoke          # handshake every server through the bridge
make stop           # quit and remove the socket

Las capturas de pantalla de la aplicación se capturan en lugar de tomarse a mano — apps/apple/Screenshots/ contiene la configuración y los goldens confirmados, y el sitio web renderiza la salida:

make screenshots          # capture, gate against the goldens, compose both sets
make screenshots-check     # gate only — fails if the UI drifted
make screenshots-update    # accept the captures as the new goldens (review the diffs first)
make screenshots-selftest  # prove the gate fails when it should

Una ejecución toma el control del puntero y de la aplicación activa en el momento de cada captura, así que no uses la máquina mientras se ejecuta. Necesita permiso de Grabación de Pantalla para la terminal, nunca para Cupertino en sí. make screenshots-doctor comprueba eso y las otras dos cosas que de otro modo fallan silenciosamente: si la fuente del título se resuelve, y si el tamaño de salida es uno que una tienda aceptaría.

Lo que muestran las capturas son datos de fixture de apps/apple/Cupertino/DemoSeed.swift, no este Mac: en -ScreenshotMode la aplicación no inicia ningún host, siembra su propio registro y sesiones, y responde a las preguntas de permiso y tienda desde una tabla. Sin eso, las imágenes reportarían el estado TCC de un portátil e imprimirían su directorio personal en el sitio de marketing.

Las sondas de fase 0 son de todo el repositorio y de solo lectura. Necesitan el permiso de la superficie que miden, y redactan su salida a recuentos, tiempos y DDL:

pnpm probe:mail      # Envelope Index — needs Full Disk Access
pnpm probe:mail-body # which lane can search message bodies — needs Full Disk Access
pnpm probe:notes     # Notes — the Apple Events half runs without it
pnpm probe:reminders # Reminders — the store path is a glob, so finding it is itself privileged
pnpm probe:messages  # chat.db — no Apple Events read lane exists, so this one needs the grant
                     #   --send-target=<handle> also checks the send lane's targeting, without sending
pnpm probe:calendar  # settles whether Calendar has a file lane at all
pnpm probe:safari    # History.db, and the Reading List hiding inside Bookmarks.plist
pnpm probe:contacts  # the resolver Messages needs — its own TCC grant, not Full Disk Access

Cada superficie sondeada ahora tiene un paquete. Safari es de solo lectura — no registra ninguna herramienta mutadora, y eso es una decisión registrada en lugar de una omisión: abrir una URL o añadir a la Lista de Lectura navega un navegador real y visible, y nunca fue sondeado. Ver docs/safari.md. Messages registra exactamente una herramienta de escritura, send_message, que es todo lo que su diccionario de scripting puede hacer. Cada sonda se degrada en lugar de salir — una aplicación que no se está ejecutando, o un permiso que no se ha concedido, se reporta como un hallazgo — y ninguna de ellas lanza una aplicación a menos que pases --launch. Su mecanismo compartido vive en scripts/lib/probe-kit.mjs.

Los lanzamientos se etiquetan por paquete, así que una etiqueta nombra lo que publica: mail-v1.1.0, reminders-v1.1.0, calendar-v1.1.0, core-v1.1.0. La aplicación se etiqueta app-v1.1.0 y se lanza en su propio carril — un Cupertino.zip firmado y notarizado adjunto al lanzamiento de GitHub, más su SHA-256. Ver docs/distribution.md.

El repositorio es mcp-cupertino; los paquetes npm siguen siendo @mgcrea/mcp-apple-*, porque eso es lo que la gente busca en npm. Ninguno de los nombres es esencial. El identificador de paquete io.mgcrea.cupertino es la cadena que realmente importa, porque cambiarlo invalidaría la concesión de Acceso Total al Disco de cada usuario.

Licencia

Dos, porque las mitades no son lo mismo.

Cupertino pide Acceso Total al Disco, así que el código fuente permanece legible — eso es lo que se debe a tal concesión, y leerlo es el punto. Ejecutarlo es una cuestión aparte: la comprobación de licencia vive en el código fuente, así que cualquier compilación pide una clave, la tuya o la nuestra. Lo que se vende es el binario notarizado y el mantenimiento detrás de él. Los servidores son MIT y funcionan por sí solos sin ninguna clave. El razonamiento está en docs/licensing.md.