# Macbeth [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/wende/macbeth  
**GitHub Stars:** 4  
**npm Downloads (last month):** 86  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/macbeth

## Description
Open-source computer use for macOS agents.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "macbeth": {
    "command": "npx",
    "args": ["-y","macbeth"]
  }
}
```

## Documentation

## What the Macbeth MCP server does

The Macbeth MCP server exposes macOS computer-use capabilities to an MCP-compatible agent. It can list running applications, connect to an application, inspect windows and controls, read roles, labels, values, enabled states, and hierarchy, and perform supported UI actions. Keyboard input and native menu selection provide alternatives when an accessibility action is unavailable.

The Macbeth MCP server uses structured accessibility data first, then falls back to screenshots and local Vision OCR when an application does not expose enough useful metadata. This makes it applicable to native macOS software, Electron applications, and some complex tools whose interfaces are only partly represented in the accessibility tree.

Bundled application skills provide workflow guidance for applications including Calendar, Contacts, Logic Pro, Mail, Maps, Messages, Music, Notes, Reminders, Safari, System Settings, and generic Electron applications. Skills describe workflows, shortcuts, known issues, and failure conditions rather than adding a separate model or agent runtime.

## How it works

The MCP server runs locally over stdio and communicates with a local daemon through a Unix-domain socket. It does not open a TCP listener. A client launches the package with `npx`, and the agent sends MCP requests for application discovery, inspection, interaction, screenshots, OCR, waits, and skill loading.

Accessibility queries are preferred for locating controls and reading state. Auto-waiting actions, lazy locators, and explicit state waits are available through the related TypeScript API. ScreenCaptureKit supplies window captures when visual inspection is required, while OCR extracts visible text from those captures.

Macbeth can also be used without MCP from TypeScript. Installing the npm package provides `connect` and the same general interaction primitives for scripts and tests.

## Setup and configuration

The Macbeth MCP server requires macOS 14 or later and Node.js 20 or later. Add it to Claude Code with:

```bash
claude mcp add macbeth -- npx -y macbeth
```

Other MCP clients that launch stdio servers can use `npx -y macbeth`. Run `npx macbeth doctor` if setup fails; the command produces diagnostic information suitable for sharing with an agent. Accessibility permission is needed for inspection and interaction. Screen Recording permission is needed only for screenshots and window OCR.

For direct TypeScript use, install the package with `npm install macbeth`, then import `connect` and attach to an application by name. Building the daemon from source additionally requires Swift 6.0 or newer, but the package provides a signed and notarized universal daemon for normal setup.

## Tools and capabilities

The Macbeth MCP server supports these grounded capability areas:

- Discovering running applications and connecting to a named application.
- Inspecting front windows and accessibility hierarchies.
- Reading control roles, labels, values, enabled states, and related structure.
- Selecting native menu items and sending keyboard input.
- Waiting for UI state changes and using auto-waiting actions.
- Capturing windows and extracting visible text with OCR.
- Loading core and application-specific skills.
- Running equivalent interaction flows from TypeScript scripts and tests.

## Limitations and notes

Application accessibility quality varies. Custom-rendered canvases, games, and some creative software may require menus, keyboard input, screenshots, OCR, or specialized skills. Changes between application versions can also break application-specific workflows.

The Macbeth MCP server can act on behalf of an agent, so it should be connected only to trusted agents. Human review is appropriate for destructive, financial, publishing, or privacy-sensitive actions. The interaction glow indicates activity but is not an approval mechanism or a complete audit log.

Screenshots requested through MCP are stored in a temporary directory and are not automatically deleted. Review the project security documentation before using the server with sensitive applications or data.

_Full upstream README: https://allmcps.com/mcp/macbeth/readme_