macOS Automator

Ejecuta scripts de AppleScript y JXA para automatizar tareas en macOS.

Documentación

macOS Automator MCP 🤖 — Dale a tu agente un Mac para operar

macOS Automator MCP es un servidor del Protocolo de Contexto de Modelos (MCP) que permite a los clientes MCP descubrir y ejecutar AppleScript o JavaScript para Automatización (JXA). Está diseñado para agentes que necesitan controlar aplicaciones de macOS, inspeccionar el sistema o reutilizar scripts de una base de conocimiento integrada.

Instalación

Necesitas macOS y Node.js 24 o superior. Añade el servidor a la configuración de tu cliente MCP; npx descarga la versión actual de npm cuando el cliente lo inicia.

{
  "mcpServers": {
    "macos_automator": {
      "command": "npx",
      "args": ["-y", "--package", "@steipete/macos-automator-mcp", "macos-automator-mcp"]
    }
  }
}

Si tu cliente tiene un campo de paquete separado, usa @steipete/macos-automator-mcp sin @latest.

Inicio rápido

Reinicia tu cliente MCP después de añadir la configuración. Primero, pídele que llame a get_scripting_tips con una búsqueda pequeña:

{
  "search_term": "Safari front tab URL",
  "limit": 3
}

Luego verifica la ejecución de scripts con un script en línea de solo lectura a través de execute_script:

{
  "script_content": "return \"Hello from macOS Automator\""
}

El resultado es Hello from macOS Automator. Las llamadas que controlan aplicaciones o la interfaz de usuario pueden solicitar permisos de macOS.

Herramientas

Herramienta	Propósito
`get_scripting_tips`	Listar categorías de la base de conocimiento o buscar consejos de AppleScript y JXA.
`execute_script`	Ejecutar un script en línea, un archivo de script o un ID de script de la base de conocimiento.

Usa get_scripting_tips antes de escribir un script desde cero. Un ID ejecutable devuelto se puede pasar a execute_script como kb_script_id; los scripts con marcadores de posición aceptan input_data con nombre o arguments posicionales.

execute_script se ejecuta con los privilegios del proceso que aloja el servidor MCP. Solo ejecuta scripts en los que confíes e inspecciona los scripts generados antes de permitir acciones destructivas. Consulta la referencia de herramientas para cada opción de entrada y respuesta.

Permisos

La aplicación que inicia el servidor MCP—como Terminal, un editor o un cliente MCP de escritorio—es la propietaria de sus permisos de privacidad de macOS:

Otorga acceso de Automatización cuando los scripts controlen Finder, Safari, Mail u otra aplicación.
Otorga acceso de Accesibilidad cuando los scripts usen Eventos del Sistema para clics, pulsaciones de teclas, menús u otro scripting de interfaz de usuario.

macOS puede mostrar un aviso de primer uso para cada aplicación de destino. El servidor no puede otorgar estos permisos por sí mismo. Consulta configuración y permisos para la configuración y los códigos de error comunes.

Base de conocimiento

El paquete incluye cientos de consejos de AppleScript y JXA que cubren tareas del sistema, archivos, navegadores, terminales, aplicaciones de productividad, herramientas de desarrollo y automatización de interfaz de usuario. Busca por palabra clave o categoría y luego ejecuta un resultado por su ID ejecutable.

Una base de conocimiento local puede añadir o sobrescribir consejos integrados sin cambiar el paquete. Su valor predeterminado es ~/.macos-automator/knowledge_base; consulta configuración y permisos para su estructura y reglas de sobrescritura.

Configuración

Variable	Valores	Predeterminado
`LOG_LEVEL`	`DEBUG`, `INFO`, `WARN`, `ERROR`	`INFO`
`KB_PARSING`	`lazy`, `eager`	`lazy`
`LOCAL_KB_PATH`	Ruta absoluta a una base de conocimiento personalizada	`~/.macos-automator/knowledge_base`

lazy carga la base de conocimiento en el primer uso; eager la carga al iniciar el servidor. Hay más detalles en configuración y permisos.

Solución de problemas

Errores de permisos como -1743 o -10004 generalmente significan que la aplicación anfitriona necesita acceso de Automatización o Accesibilidad.
Los errores de sintaxis de scripts son más fáciles de aislar con include_executed_script_in_output y include_substitution_logs, y luego reproducirlos en Script Editor.
Usa una ruta POSIX absoluta con script_path y aumenta timeout_seconds para scripts que legítimamente necesiten más de 60 segundos.
JXA normalmente funciona mejor con output_format_mode: "direct"; el modo auto predeterminado lo selecciona para JXA.

Consulta Depuración de AppleScript y JXA para una guía de diagnóstico más extensa.

Desarrollo

pnpm install
pnpm run build
pnpm test
pnpm run lint
pnpm run validate

El repositorio usa pnpm 11 y Node.js 24. La guía de desarrollo cubre la configuración del servidor local y las contribuciones a la base de conocimiento.

Comunidad

Reporta errores y propón scripts en GitHub Issues.

Licencia

MIT