Macbeth

Macbeth — Uso de computadora de código abierto para macOS

Dale al agente que ya usas manos y ojos en tu Mac.

Ve y opera aplicaciones de Mac a través de MCP o TypeScript, incluyendo interfaces nativas y Electron.

Acceso estructurado a la interfaz cuando sea posible. Capturas de pantalla y OCR cuando sea necesario.
Piensa en Playwright para todo tu Mac.

_{Recorrido simulado de la superficie de herramientas MCP actual de Macbeth: Configuración del Sistema, interacción con Electron y captura de pantalla/OCR.}

Inicio rápido · Ejemplos · ¿Por qué Macbeth? · TypeScript · Seguridad · Habilidades

Inicio rápido

Dale a Claude Code acceso a Macbeth:

claude mcp add macbeth -- npx -y macbeth

Luego pídele que verifique la conexión:

Usando Macbeth, lista las aplicaciones en ejecución, conéctate a Finder, inspecciona su ventana frontal y resume los primeros controles que puedas ver. No realices ninguna otra acción.

Macbeth incluye un daemon universal precompilado, firmado y notarizado. No se requiere cadena de herramientas Swift ni instalación manual de servicios. Si la configuración falla, ejecuta npx macbeth doctor; imprime un mensaje de diagnóstico autocontenido que puedes pegar de vuelta en tu agente.

Cualquier cliente MCP que pueda lanzar un servidor stdio puede usar npx -y macbeth. Consulta Configuración de MCP para configuración genérica, actualizaciones y la lista completa de herramientas.

Deja que tu agente guíe la instalación

Agrega Macbeth como servidor MCP usando npx -y macbeth. Ejecuta npx macbeth doctor, guíame para otorgar solo los permisos que necesito y verifica la configuración inspeccionando Finder. No realices acciones no relacionadas.

En todo tu Mac

Trabaja dentro de Unity, Logic Pro y otras herramientas complejas

"En Logic Pro, establece el tempo del proyecto a 128 BPM e inicia la reproducción."

Macbeth combina controles estructurados, menús, entrada de teclado, capturas de pantalla, OCR y orientación específica de la aplicación. Logic Pro tiene una habilidad dedicada. Las aplicaciones con árboles de accesibilidad más delgados, incluidas partes de Unity, pueden combinar controles estructurados con teclado, menú, captura de pantalla y respaldos de OCR.

Automatiza macOS en sí

"Abre Configuración del Sistema, encuentra los controles del firewall e informa su estado actual sin cambiar nada."

Macbeth puede inspeccionar controles y valores nombrados, seleccionar elementos de menú nativos y usar entrada de teclado cuando una acción semántica no está disponible.

Usa aplicaciones incluso cuando no tienen API

"Abre HEY, encuentra el hilo visible más reciente del equipo de diseño y resúmelo sin enviar ni cambiar nada."

Macbeth puede trabajar a través de interfaces Electron expuestas incluso cuando el servicio no proporciona la API que tu agente necesita. HEY funciona a través del soporte genérico de Electron de Macbeth; los resultados varían con el árbol de accesibilidad y la versión de la aplicación.

Ve lo que el árbol de accesibilidad no captura

"Captura la ventana frontal de Notas y extrae todo el texto visible."

Las capturas de pantalla de ScreenCaptureKit y el OCR local de Vision proporcionan un respaldo para contenido que macOS no expone como datos de accesibilidad útiles.

Crea scripts y pruebas repetibles

El mismo motor está disponible como API de TypeScript con localizadores perezosos, acciones de espera automática, esperas de estado explícitas, capturas de pantalla y conexiones de aplicaciones.

[!IMPORTANTE] Macbeth puede actuar dentro de aplicaciones en tu nombre. Conecta solo agentes confiables y requiere aprobación para acciones de consecuencias importantes.

¿Por qué Macbeth?

• Usa tu propio agente. Macbeth es una capa de control, no un modelo ni un runtime de agente.
• Estructurado cuando sea posible. Consulta roles, etiquetas, valores, estado habilitado, jerarquía y manejadores estables en lugar de depender solo de coordenadas.
• Visual cuando sea necesario. Recurre a captura de ventanas y OCR cuando los metadatos de accesibilidad son escasos.
• Consciente de la aplicación. Las habilidades versionadas preservan flujos de trabajo, atajos y modos de fallo conocidos.
• Programable. Usa los mismos primitivos de forma interactiva a través de MCP o directamente desde TypeScript.

Estructurado antes que píxeles

Capacidad	Agente típico basado en capturas	Macbeth
Encontrar un control etiquetado	Inferencia visual	Consulta de accesibilidad cuando está expuesta
Leer rol, valor y estado	Inferido	Atributos estructurados
Esperar un cambio de interfaz	Generalmente observado mediante capturas repetidas	Esperas explícitas y acciones de espera automática
Manejar metadatos de interfaz incompletos	Visión/OCR	Accesibilidad primero, respaldo de captura/OCR
Reutilizar conocimiento de aplicaciones	Dependiente del prompt	Habilidades empaquetadas y versionadas

La información de accesibilidad puede ser en sí misma incompleta o engañosa. Macbeth es una interfaz híbrida: usa primitivos estructurados más fuertes cuando macOS los expone y mantiene respaldos visuales y a nivel de sistema disponibles cuando no lo hace.

Seguridad y limitaciones

• Macbeth requiere macOS 14 o más reciente y Node.js 20 o más reciente.
• Se requiere permiso de Accesibilidad para inspección e interacción de interfaz. La Grabación de Pantalla se requiere solo para capturas de pantalla y OCR de ventanas.
• La calidad de accesibilidad de las aplicaciones varía. Los lienzos renderizados personalizados, juegos y algunas herramientas creativas pueden requerir menús, capturas de pantalla, OCR, entrada de teclado u orientación específica de la aplicación.
• Los cambios de interfaz entre versiones de aplicaciones pueden romper flujos de trabajo especializados.
• El brillo de interacción hace visible la actividad de Macbeth, pero no es un sistema de aprobación ni un registro de auditoría completo.
• Los agentes pueden cometer errores. Usa revisión humana para acciones destructivas, financieras, de publicación o sensibles a la privacidad.

Macbeth usa un servidor MCP stdio local y un socket de dominio Unix; no abre un listener TCP. Las capturas de pantalla solicitadas a través de MCP se escriben en un directorio temporal y no se eliminan automáticamente. Lee el modelo de seguridad para el flujo de datos, revocación de permisos, riesgos de procesos locales y prácticas operativas más seguras.

API de TypeScript

npm install macbeth

import { connect } from "macbeth";

const app = await connect("TextEdit");
await app.window("Untitled").textField().fill("Hello from Macbeth");
await app.pressKey("s", ["cmd"]);

Consulta Desarrollando con Macbeth para localizadores, capturas de pantalla, comportamiento de Electron, ciclo de vida y pruebas.

Enseña a Macbeth una aplicación

Una habilidad de Macbeth es un archivo SKILL.md, opcionalmente acompañado de scripts ejecutables, que enseña a un agente flujos de trabajo confiables y trampas. Llama a load_skill sin argumentos para la guía principal de Macbeth. Las habilidades de aplicaciones empaquetadas cubren Calendario, Contactos, Logic Pro, Correo, Mapas, Mensajes, Música, Notas, Recordatorios, Safari, Configuración del Sistema y aplicaciones Electron genéricas.

Puedes agregar una habilidad sin cambiar el daemon Swift. Comienza con la guía de contribución e incluye un prompt reproducible, versión de aplicación probada, resultado esperado y modos de fallo honestos.

Documentación

Guía	Contenido
Servidor MCP	Instalación, prueba de humo, herramientas, habilidades y actualizaciones
CLI	Cada herramienta MCP como subcomando macbeth <tool>
API de TypeScript	API de cliente, localizadores, Electron y pruebas
Arquitectura	Daemon, protocolo, respaldos y notas de diseño
Seguridad	Límites de confianza, manejo de datos y revocación de permisos
Solución de problemas	Diagnósticos y fallos de configuración comunes
Contribución	Flujo de trabajo de desarrollo y habilidades de aplicaciones

Requisitos

• macOS 14 (Sonoma) o posterior
• Node.js 20+
• Swift 6.0+ solo al compilar el daemon desde el código fuente

Licencia

MIT