macos-mcp

Controla Recordatorios, Calendario, Notas, Correo, Mensajes y Contactos en macOS desde un agente de IA, o desde la terminal.

Apple expone tres superficies de automatización para estas aplicaciones, y cada una falla en algún punto. EventKit no llega a Notas, Correo, Mensajes o Contactos. Las lecturas JXA de Mensajes no devuelven nada en Sonoma y versiones posteriores. Las lecturas JXA de Correo agotan el tiempo de espera a los 60 segundos con una bandeja de entrada real. Este proyecto utiliza el puente que funciona para cada aplicación y documenta el porqué en DECISION.md.

Requiere un Mac. Estos puentes son EventKit, Apple Events y lecturas SQLite de bases de datos locales de Apple. No hay compilación para Linux, Windows, iOS, Android o navegador.

Tres formas de usarlo

Como servidor MCP. Transporte stdio local, funciona con cualquier cliente compatible con MCP en el mismo Mac (Claude Code, Claude Desktop, Cursor, Zed, Continue, escritorio de ChatGPT). Ocho herramientas, enumeradas en Herramientas.

Como habilidad de agente. Los mismos puentes llamados como comandos de shell, sin esquemas de herramientas cargados en el contexto. Un servidor MCP pone las ocho definiciones de herramientas frente al modelo al inicio de la sesión, toque o no la sesión una aplicación de Mac; una habilidad es una línea de descripción hasta que algo la activa. Consulta skills/macos/ para la habilidad y docs/mcp-vs-skill.md para saber cómo elegir.

Como CLI. EventKitCLI es un binario Swift independiente que habla JSON en stdout. Las recetas JXA y SQLite de la habilidad se ejecutan en cualquier lugar donde haya un shell.

Related MCP server: Apple MCP

Inicio rápido

Instalar como plugin de Claude Code

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

Ejecuta estos comandos dentro de Claude Code. El plugin conecta el servidor MCP mediante npx -y mcp-macos, por lo que no se requiere un paso de instalación por separado.

Instalar desde npm

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

O instalar mediante MCPB (Claude Desktop)

Descarga el paquete .mcpb desde la última versión de GitHub y arrástralo a Claude Desktop. El paquete incluye un binario Swift universal precompilado (arm64 + x86_64), por lo que no se requieren Xcode Command Line Tools.

O compilar desde el código fuente

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

Verificar la configuración

macos-mcp --check   # or: node dist/index.js --check

Comprueba la versión de macOS, Node.js, el binario de EventKit, el Acceso total al disco y los permisos de automatización JXA.

O usarlo como habilidad en lugar de un servidor

Copia la habilidad en el directorio de habilidades de tu agente. Sin servidor MCP, sin esquemas de herramientas en el contexto.

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

La habilidad llama directamente a EventKitCLI, osascript y sqlite3, por lo que necesita el binario Swift en PATH:

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

Los mismos permisos se aplican de cualquier manera. Consulta Permisos.

Herramientas

Tanto la notación con guion bajo (reminders_tasks) como con punto (reminders.tasks) funcionan.

Notas de diseño

• SQLite para lecturas, JXA para escrituras. Las lecturas JXA de Correo no escalan, alcanzando tiempos de espera de 60 s en bandejas de entrada reales, y las lecturas JXA de Mensajes están completamente rotas en macOS Sonoma y versiones posteriores. Este proyecto lee chat.db y el Envelope Index de Correo directamente, incluida la tabla de unión labels de Gmail para cuentas [Gmail]/All Mail. Las escrituras siguen pasando por JXA, porque Apple Events es la única API que las activa. Consulta ADR-001.

• Backend híbrido por aplicación. Cada aplicación usa el puente que funciona: un CLI Swift a través de EventKit para Recordatorios y Calendario, JXA para Notas, Contactos, escrituras de Correo y envío de Mensajes, SQLite para lecturas de Correo y Mensajes. El diagrama de arquitectura muestra la distribución.

• Enriquecimiento de contactos entre herramientas. Una capa compartida resuelve números de teléfono y direcciones de correo sin procesar a nombres de contacto en Mensajes, Correo y Calendario. Caché masiva mediante el almacén SQLite de AddressBook, en menos de 50 ms para 1.100 entradas; búsquedas específicas mediante JXA whose(). Consulta ADR-002.

• Comprobación previa. macos-mcp --check valida la versión de macOS, Node.js, el binario de EventKit, el Acceso total al disco y los permisos JXA antes de la ejecución, con enlaces profundos a los paneles de Ajustes del Sistema correspondientes para cualquier cosa que falle.

Configuración

Requisitos previos

• Node.js 20+

• macOS

• Xcode Command Line Tools (compilación Swift)

Configuración del cliente

La configuración JSON es la misma para todos los clientes. Solo difiere la ubicación.

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": ["mcp-macos"]
    }
  }
}

Permisos

macOS solicita acceso en el primer uso. Haz clic en Permitir cuando se te pida.

Mensajes y Correo leen bases de datos SQLite directamente, por lo que tu aplicación de terminal (Terminal, iTerm2, etc.) necesita Acceso total al disco.

Ejecuta macos-mcp --check para verificar. Consulta Solución de problemas si algo falla.

Solución de problemas

Comandos de corrección rápida

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Acceso total al disco (Mensajes y Correo)

Mensajes y Correo leen bases de datos SQLite (~/Library/Messages/chat.db y ~/Library/Mail/V10/MailData/Envelope Index). Estas requieren Acceso total al disco en tu aplicación de terminal.

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Usuarios de gestores de versiones (Volta, nvm, fnm): el comando node es un shim. Ajustes del Sistema necesita el binario real:

Ajustes del Sistema puede no mostrar binarios en directorios ocultos. Usa open -R arriba para revelarlo en Finder y luego arrástralo a la lista de FDA.

Automatización JXA (Notas, Correo, Contactos)

En el primer uso, macOS solicita acceso de Automatización. Concédelo mediante Ajustes del Sistema > Privacidad y seguridad > Automatización.

Verificar permisos:

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

Cada comando debería devolver un valor. Un cuelgue significa que el diálogo de permisos está intentando (y fallando) aparecer.

Etiquetas de Gmail / Mensajes de bandeja de entrada faltantes

Gmail almacena todos los mensajes en [Gmail]/All Mail y usa etiquetas para la pertenencia a carpetas. El servidor comprueba tanto el buzón directo como la tabla de unión de etiquetas. Si faltan mensajes de la bandeja de entrada de Gmail, verifica que la aplicación Correo se haya sincronizado por completo.

Desarrollo

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

El punto de entrada de producción (bin/run.cjs) requiere pnpm build. Usa pnpm dev para el desarrollo local.

Arquitectura

flowchart LR
    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]

Tres puentes hacia las aplicaciones de Apple:

• EventKit (binario Swift). Recordatorios, Calendario. CLI Swift compilado, devuelve JSON.

• JXA. Notas, escrituras de Correo, Contactos. Los scripts se ejecutan mediante osascript -l JavaScript.

• SQLite. Lecturas de Mensajes (~/Library/Messages/chat.db), lecturas de Correo (~/Library/Mail/V10/MailData/Envelope Index). La lectura de mensajes JXA está rota en Sonoma y versiones posteriores. La lectura de correo JXA es demasiado lenta para bandejas de entrada reales.

Correo y Mensajes usan una ruta híbrida: JXA para escrituras (única forma de activar envío/borrador), SQLite para lecturas (la única que escala). Consulta DECISION.md para los registros de decisiones de arquitectura.

Dependencias

Tiempo de ejecución: @modelcontextprotocol/sdk, zod

Desarrollo: typescript, tsx, jest, @biomejs/biome

Créditos

La capa del servidor MCP comenzó a partir de FradSer/mcp-server-apple-events (MIT). El CLI Swift de EventKit, las rutas de lectura SQLite, el enriquecimiento de contactos, la comprobación previa y la superficie de habilidad se añadieron aquí.

Licencia

MIT

Contribuciones

Consulta CONTRIBUTING.md.