🍏 Uso de Computadora en macOS (Servidor MCP)

Un servidor Model Context Protocol (MCP) nativo y ultrarrápido que brinda a los LLM y agentes autónomos inspección visual y automatización de escritorio con cierre seguro en macOS.

Construido con un núcleo Swift compilado que aprovecha las CoreGraphics nativas de Apple, Vision OCR (VNRecognizeTextRequest) y API de Accesibilidad para acciones de fondo semánticas. La entrada no dirigida sigue siendo un respaldo explícito de CoreGraphics global.

⚡ Aspectos Destacados

• 🎯 OCR nativo de Apple Vision (find_text / click_text): Encuentra texto visible con coincidencia explícita exact, word, prefix o substring y rechaza clics ambiguos a menos que se seleccione una ocurrencia.

• 🛡️ Segmentación con cierre seguro: windowId es autoritativo. Los ID no válidos y las discrepancias entre aplicación y ventana devuelven errores en lugar de recurrir a otra ventana o a la pantalla completa.

• 🔐 Seguro por defecto: La entrada global de puntero/teclado, la activación de la aplicación en primer plano y el AppleScript personalizado están deshabilitados a menos que el proceso MCP se inicie con MACOS_COMPUTER_USE_UNSAFE=1.

• 🩺 Verificación previa de permisos: get_capabilities informa sobre la preparación de Accesibilidad, Grabación de Pantalla y síntesis de eventos sin llamar a las API de solicitud de permisos de macOS.

• ♿ Acciones de Accesibilidad en segundo plano: Inspecciona controles, establece valores, ejecuta acciones semánticas y apunta a controles editables sin activar su aplicación.

• ⏱️ Espera semántica en segundo plano: Espera a que aparezcan controles de Accesibilidad sin tomar una captura de pantalla ni requerir Grabación de Pantalla.

• 🖱️ Cursor de agente en vivo: Los clics y el desplazamiento deslizan un cursor superpuesto distintivo y transparente hacia el objetivo, muestran comentarios de éxito o fracaso y se desvanecen cuando están inactivos sin mover el puntero físico.

• 👁️ Cursor coincidente en capturas de pantalla (mark_cursor): Las capturas de pantalla de acciones devueltas representan el mismo cursor de agente en la coordenada objetivo.

• ⚡ Sincronización reactiva de la interfaz (wait_for_text): Reemplaza los tiempos de espera ciegos sleep() con un bucle de sondeo OCR de alta velocidad que se resuelve en el instante en que aparecen menús desplegables de autocompletado dinámicos, modales o cambios de estado.

• 🖼️ Captura de pantalla aislada por ventana: Captura los búferes de la aplicación objetivo limpiamente en segundo plano (screencapture -l <wid> -o -x) sin traer la ventana al frente ni capturar ventanas superpuestas.

Related MCP server: ScreenHand

🛠️ Herramientas Expuestas

🚀 Instalación y Configuración

Ejecutar con npx

Configura un cliente MCP para descargar, compilar e iniciar el último paquete público:

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

El paquete incluye un helper Swift universal firmado ad-hoc para Macs con Apple Silicon e Intel, por lo que npx no requiere un compilador Swift local ni aprobación de script de instalación.

La configuración predeterminada expone automatización semántica en segundo plano e inspección de solo lectura. Para flujos de trabajo que necesitan intencionalmente entrada global de puntero/teclado, activación en primer plano o AppleScript arbitrario, opta explícitamente:

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"],
      "env": {
        "MACOS_COMPUTER_USE_UNSAFE": "1"
      }
    }
  }
}

1. Requisitos previos

• macOS 13.0+ (Apple Silicon o Intel)

• Node.js 20+

• Xcode Command Line Tools solo al compilar desde el código fuente:

  xcode-select --install

2. Clonar y compilar

git clone https://github.com/johnexzy/macos-computer-use.git
cd macos-computer-use
npm install
npm run build

🔒 Permisos de macOS basados en capacidades

Solo otorga el permiso necesario para las herramientas que uses. macOS atribuye el permiso a la aplicación anfitriona que ejecuta el servidor MCP (Terminal, OpenCode, Cursor, VS Code, etc.):

1. Accesibilidad: Requerido para inspección y acciones semánticas. No requiere Grabación de Pantalla.

2. Grabación de Pantalla y Audio del Sistema: Requerido solo para capturas de pantalla y herramientas de OCR de Vision como screenshot, find_text, click_text y wait_for_text.

3. Síntesis de eventos: Los clics globales de CoreGraphics, escritura, pulsaciones de teclas y desplazamiento en modo inseguro requieren acceso de publicación de eventos. Las acciones semánticas de Accesibilidad no usan este respaldo global.

4. Automatización: macOS puede solicitarla solo cuando el modo inseguro está habilitado y run_applescript envía un evento a otra aplicación. Las herramientas de entrada y fondo principales usan el helper nativo en lugar de System Events.

Llama a get_capabilities antes de operaciones protegidas. La inspección de permisos usa las API de verificación previa de Apple y no abre un aviso de permiso. Si falta el acceso, las rutas de captura de pantalla/OCR y entrada global devuelven SCREEN_RECORDING_PERMISSION_REQUIRED o INPUT_POSTING_PERMISSION_REQUIRED antes del envío. Otorga acceso manualmente en Configuración del Sistema y luego reconecta el MCP si el anfitrión aún mantiene un estado de privacidad obsoleto.

macOS aún puede requerir que la aplicación anfitriona se reinicie después de un permiso de privacidad recién otorgado. Esto lo impone macOS; el servidor no solicita repetidamente ni pide permisos no relacionados.

La automatización de la interfaz en segundo plano es cooperativa: macOS puede dirigirse a elementos de Accesibilidad en otro proceso, pero una aplicación puede ignorar eventos de teclado dirigidos o cambiar sus identificadores en una versión posterior. Estas herramientas devuelven errores explícitos de no admitido/no confirmado en esos casos en lugar de activar la aplicación o informar un éxito falso.

🔌 Configuración de MCP

Agrega este servidor a la configuración de tu cliente MCP:

Antigravity / Claude Desktop / Cursor / Windsurf

Agrega a tu mcp_config.json / claude_desktop_config.json:

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/macos-computer-use/server.mjs"]
    }
  }
}

🧪 Probando el Helper Swift Nativo Directamente

Puedes probar el binario nativo directamente desde tu terminal:

# Display resolution and scaling
./native_helper size

# List active Chrome windows in Z-order
./native_helper list_windows "Google Chrome"

# Find a button or text on screen with Apple Vision OCR in ~30ms
./native_helper find_text "Search" "Google Chrome"

# Reactively wait for dynamic text to appear
./native_helper wait_for_text "quantum" "Google Chrome" nil 5.0

Ejecuta las regresiones automatizadas de cierre seguro y coincidencia:

npm test

Verifica la inspección semántica contra una ventana de Calculadora en segundo plano:

npm run test:background -- Calculator

Con Calculadora y Configuración del Sistema abiertas, ejecuta la suite de humo de la aplicación nativa en vivo. La prueba opta por el modo inseguro porque usa AppleScript para crear y limpiar archivos de TextEdit:

npm run test:live

Los resultados de herramientas mutantes incluyen un objeto execution con un contrato versionado, método de entrega, nivel de verificación, estado de preservación del primer plano y objetivo. Las acciones basadas en coordenadas conservan status: "delivered_unverified"; verifica el estado posterior consecuente con inspección semántica, OCR o una captura de pantalla.

El servidor MCP inicia un proceso de superposición de cursor perezosamente en el primer clic o desplazamiento y lo detiene cuando se cierra la conexión MCP. La superposición nunca intercepta la entrada del mouse, se une a todos los Spaces y ventanas de pantalla completa, e informa cursorOverlay.status: "unavailable" sin bloquear la acción solicitada si AppKit no puede mostrarla.

📦 Publicación

Los envíos a main ejecutan el flujo de trabajo de publicación npm. Para lanzar una nueva versión, actualiza la versión en package.json y package-lock.json antes de fusionar. Las versiones que ya existen en npm se prueban y se omiten.

📄 Licencia

MIT © John Oba