Macbeth
About
Open-source computer use for macOS agents.
Details
- Author
- wende
- Categories
- Productivity, Other
Jump to
Setup
Install Macbeth in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/wende/macbeth
Follow the installation instructions in the repository README, then restart your MCP client.
Macbeth — Open-source Computer Use for macOS
Give the agent you already use hands and eyes on your Mac.
See and operate Mac applications through MCP or TypeScript, including native and Electron interfaces.
Structured UI access when possible. Screenshots and OCR when necessary.
Think Playwright for your entire Mac.
Simulated walkthrough of Macbeth's current MCP tool surface: System Settings, Electron interaction, and screenshot/OCR.
Quickstart·Examples·Why Macbeth?·TypeScript·Security·Skills
claude mcp add macbeth -- npx -y macbeth
Using Macbeth, list the running applications, connect to Finder, inspect its front window, and summarize the first few controls you can see. Do not perform any other actions.
Macbeth ships with a prebuilt, signed and notarized universal daemon. No Swift toolchain or manual service installation is required. If setup fails, runnpx macbeth doctor; it prints a self-contained diagnostic prompt you can paste back into your agent.
Any MCP client that can launch a stdio server can usenpx -y macbeth. SeeMCP setupfor generic configuration, updates, and the complete tool list.
Add Macbeth as an MCP server usingnpx -y macbeth. Runnpx macbeth doctor, guide me through granting only the permissions I need, and verify the setup by inspecting Finder. Do not take any unrelated actions.
Work inside Unity, Logic Pro, and other complex tools
“In Logic Pro, set the project tempo to 128 BPM and start playback.”
Macbeth combines structured controls, menus, keyboard input, screenshots, OCR, and application-specific guidance. Logic Pro has adedicated skill. Applications with thinner accessibility trees, including parts of Unity, can combine structured controls with keyboard, menu, screenshot, and OCR fallbacks.
“Open System Settings, find the firewall controls, and report their current state without changing anything.”
Macbeth can inspect named controls and values, select native menu items, and use keyboard input when a semantic action is unavailable.
Use applications even when they have no API
“Open HEY, find the newest visible thread from the design team, and summarize it without sending or changing anything.”
Macbeth can work through exposed Electron interfaces even when the service does not provide the API your agent needs. HEY works through Macbeth's genericElectron support; results vary with the application's accessibility tree and version.
“Capture the frontmost Notes window and extract all visible text.”
ScreenCaptureKit screenshots and local Vision OCR provide a fallback for content that macOS does not expose as useful accessibility data.
The same engine is available as a TypeScript API with lazy locators, auto-waiting actions, explicit state waits, screenshots, and application connections.
[!IMPORTANT] Macbeth can act inside applications on your behalf. Connect only trusted agents and require approval for consequential actions.
- Use your own agent.Macbeth is a control layer, not a model or agent runtime.
- Structured when possible.Query roles, labels, values, enabled state, hierarchy, and stable handles instead of relying only on coordinates.
- Visual when necessary.Fall back to window capture and OCR when accessibility metadata is thin.
- Application-aware.Versioned skills preserve workflows, shortcuts, and known failure modes.
- Scriptable.Use the same primitives interactively over MCP or directly from TypeScript.
Accessibility information can itself be incomplete or misleading. Macbeth is a hybrid interface: it uses stronger structured primitives when macOS exposes them and keeps visual and system-level fallbacks available when it does not.
- Macbeth requires macOS 14 or newer and Node.js 20 or newer.
- Accessibility permission is required for UI inspection and interaction. Screen Recording is required only for screenshots and window OCR.
- Application accessibility quality varies. Custom-rendered canvases, games, and some creative tools may require menus, screenshots, OCR, keyboard input, or application-specific guidance.
- Interface changes between application versions can break specialized workflows.
- The interaction glow makes Macbeth activity visible, but it is not an approval system or a complete audit log.
- Agents can make mistakes. Use human review for destructive, financial, publishing, or privacy-sensitive actions.
Macbeth uses a local stdio MCP server and a Unix-domain socket; it does not open a TCP listener. Screenshots requested through MCP are written to a temporary directory and are not automatically deleted. Read thesecurity modelfor data flow, permission revocation, local-process risks, and safer operating practices.
import { connect } from "macbeth"; const app = await connect("TextEdit"); await app.window("Untitled").textField().fill("Hello from Macbeth"); await app.pressKey("s", ["cmd"]);
SeeDeveloping with Macbethfor locators, screenshots, Electron behavior, lifecycle, and tests.
A Macbeth skill is aSKILL.mdfile, optionally accompanied by runnable scripts, that teaches an agent reliable workflows and pitfalls. Callload_skillwith no arguments for thecore Macbeth guide. Bundled app skills cover Calendar, Contacts, Logic Pro, Mail, Maps, Messages, Music, Notes, Reminders, Safari, System Settings, and generic Electron applications.
You can add a skill without changing the Swift daemon. Start with thecontribution guideand include a reproducible prompt, tested application version, expected result, and honest failure modes.
- macOS 14 (Sonoma) or later
- Node.js 20+
- Swift 6.0+ only when building the daemon from source
Enables LLM clients to interact with macOS applications through AppleScript. Built using the @beyondbetter/bb-mcp-server library, this server provides safe, controlled execution of predefined scripts with optional support for arbitrary script execution.
On-device tools to detect AI-generated text and images, score readability, and strip AI artifacts, running locally on Apple silicon.
Interact with Apple Notes using natural language on macOS.
Free local MCP server for Apple Mail, Calendar, and Reminders on macOS.
A server for native integration with Apple Reminders on macOS.
Execute AppleScript to gain full control of your Mac.
Native macOS Calendar & Reminders MCP server with 24 tools using Swift EventKit - supports recurring events, location triggers, search, batch operations
Native macOS Calendar & Reminders MCP server via Apple EventKit — events, reminders, recurrence, location triggers, conflict checks, and batch ops across iCloud/Google/Exchange.
An MCP server for integrating with the Claude Desktop application on macOS. Requires the Claude Desktop app to be installed and configured.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
