Log inSubmit server
Macbeth logo

Macbeth

Controls macOS applications through MCP using accessibility data, keyboard input, screenshots, OCR, and application skills.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Macbeth

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "macbeth": {
      "command": "npx",
      "args": [
        "-y",
        "macbeth"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command didn't complete successfully in our automated test.

npx -y macbeth

major version of npm available! 10.1.0 -> 12.2.0 npm notice Changelog: <https://github.com/npm/cli/releases/tag/v12.2.0> npm notice Run `npm install -g npm@12.2.0` to update! npm notice npm ERR! code EBADPLATFORM npm ERR! notsup Unsupported platform for macbeth@0.2.4: wanted {"os":"darwin"} (current: {"os":"linux"}) npm ERR! notsup Valid os: darwin npm ERR! notsup Actual os: linux npm ERR! A complete log of this run can be found in: /home/user/.npm/_logs/2026-10-21T11_51_30_782Z-debug-0.log

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 6d ago.

Overview

Macbeth MCP server gives AI agents structured and visual control over macOS applications through a local stdio MCP service. It can inspect applications and windows, query accessibility data, interact with controls and menus, send keyboard input, capture screenshots, and use local OCR when needed. Use it for agent-driven desktop workflows, applications without suitable APIs, or repeatable macOS automation. It requires macOS 14 or newer, Node.js 20 or newer, and appropriate macOS permissions.

Use cases

  • Inspect running macOS applications and summarize visible controls
  • Automate native application workflows through accessibility controls
  • Operate Electron applications without relying on their service APIs
  • Extract visible text from windows with screenshots and OCR
  • Build repeatable macOS UI scripts and tests in TypeScript

Key features

  • Accessibility-tree inspection and structured UI queries
  • Keyboard input and native menu interaction
  • Screenshot capture with local Vision OCR
  • Application connections with waits and auto-waiting actions
  • Bundled application and Electron skills
  • MCP and TypeScript interfaces

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

8/8 checks healthy over the last 44d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 12d ago via OSV.dev · macbeth (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars4Stargazers on the source repository.
npm downloads86Package downloads in the last 30 days.
Last commit1mo agoMost recent push to the default branch.
Install checkInconclusiveInstall command did not finish in our automated test.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Macbeth works

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:

Terminal
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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Macbeth

Macbeth is an MCP server that connects AI agents to macOS applications through a local stdio service. Its main tools support application discovery and connections, accessibility-tree inspection, UI interaction, keyboard input, menus, screenshots, OCR, waits, and skill loading. It requires macOS 14+ and permissions for the operations used.

Install it for Claude Code with `claude mcp add macbeth -- npx -y macbeth`. Any MCP client that launches stdio servers can use `npx -y macbeth`. The package includes a signed and notarized daemon, so a Swift toolchain is not needed for the normal installation.

Accessibility permission is required for UI inspection and interaction. Screen Recording permission is required for screenshots and window OCR, but not for other accessibility-based operations. The server requires macOS 14 or newer and Node.js 20 or newer.

Yes, Macbeth can work with Cursor if it launches standard stdio MCP servers.

Yes, Macbeth can interact with applications through exposed native or Electron interfaces even when the service lacks a suitable API. Results depend on the application's accessibility tree and version, and screenshots, OCR, keyboard input, menus, or application-specific skills may be needed.

Related MCP servers

All in OS Automation All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMacbeth AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/macbeth?style=directory)](https://allmcps.com/mcp/macbeth)
HTML Embed
<a href="https://allmcps.com/mcp/macbeth"><img src="https://allmcps.com/api/badge/macbeth?style=directory" alt="Macbeth on AllMCPs" /></a>