mac-control-mcp

Native Swift MCP server for full macOS automation. 63 tools in one signed .app bundle — no Python, no Node runtime, no Electron.

Gives any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) the ability to:

• Read and mutate the Accessibility tree of any running app
• Drive Safari and Chrome (tabs, navigation, JS eval)
• Capture the screen, a display, or a specific window (ScreenCaptureKit)
• OCR what's on screen
• Click, type, scroll, drag, send key events
• Control windows (move / resize / fullscreen / minimize / main)
• Manage the clipboard
• Launch / activate / quit apps
• Search Spotlight's index (NSMetadataQuery) and launch results
• Toggle dark mode, volume, list displays, inspect menus

Install

Requires macOS 14.0+. Three options, in order of simplicity:

1. One-click install (Claude Desktop, recommended)

The server is published as an MCP Bundle — a zip with a manifest.json that Claude Desktop reads directly:

1. Download mac-control-mcp-v0.2.1.mcpb from the release page.
2. Double-click the .mcpb file. Claude Desktop opens an install dialog.
3. Click Install. The server is registered under the name mac-control-mcp and available immediately in new chats.
4. First tool call triggers the macOS TCC consent prompts (Screen Recording, Accessibility, Apple Events). Grant all three once — the bundle is Developer-ID signed and notarized, so grants persist across updates.

It's also listed on the official MCP Registry as io.github.AdelElo13/mac-control-mcp, so any MCP client that supports the registry will find it by searching for "mac-control".

2. Download the prebuilt app

If you don't use Claude Desktop or want manual control:

1. Download MacControlMCP-v0.2.1-macos-universal.tar.gz.
2. Extract and move MacControlMCP.app to ~/Applications/.
3. Point your MCP client at the binary inside:

{
  "mcpServers": {
    "mac-control-mcp": {
      "type": "stdio",
      "command": "/Users/you/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP"
    }
  }
}

Add that block to ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop) or ~/.claude.json → mcpServers (Claude Code).

Verify the download with the published SHA-256:

shasum -a 256 MacControlMCP-v0.2.1-macos-universal.tar.gz
# should match MacControlMCP-v0.2.1-macos-universal.sha256 on the release

3. Build from source

For contributors or if you want to tweak the code. Requires Swift 6 / Xcode 16+:

git clone https://github.com/AdelElo13/mac-control-mcp.git
cd mac-control-mcp
./scripts/build-bundle.sh

Produces ~/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP. Without a Developer ID cert in your keychain it'll fall back to ad-hoc signing (works for local use, TCC grants reset on every rebuild).

To re-sign + re-notarise an existing Apple Developer account:

# one-time: store notary credentials in keychain
xcrun notarytool store-credentials "mac-control-mcp" \
    --apple-id "you@example.com" --team-id "XXXXXXXXXX"

# subsequent builds:
NOTARIZE_PROFILE=mac-control-mcp ./scripts/build-bundle.sh

Tool surface

Total: 63 tools.

Security model

• Tools that write files (capture_*, ocr_screen) validate output_path via a strict allow-list — only the user-scoped temp dir (NSTemporaryDirectory()) and ~/Desktop, ~/Documents, ~/Downloads, ~/Pictures are accepted. Symlinks at the target path are rejected to prevent redirection. /tmp is deliberately excluded because it's shared across users and opens a TOCTOU window.
• AppleScript string interpolation for browser_eval_js wraps user code in (0, eval)(…) via JSON.stringify, so quotes/newlines/unicode can't break out of the wrapper.
• No network calls. Everything is local system integration.

Status (verified in the current release)

If you run into an untested path, please open an issue with the reproduction — happy to fix fast.

Caveats

• Cross-origin iframes block browser_eval_js — same-origin policy, not a limitation of the tool. Use AX coords or synthetic CGEvents for content inside embedded iframes from other origins.
• First-run TCC prompts are unavoidable. macOS requires the user to grant Screen Recording, Accessibility and Apple Events the first time. The usage-description strings in Info.plist make the consent dialogs show up with a clear reason, but you still need to click Allow in System Settings once.

Development

# Run the test suite (63 tests in 11 suites)
swift test

# Build without packaging
swift build -c release

# Live probe the running binary via MCP stdio
python3 scripts/mcp-sweep.py  # if included

License

MIT — see LICENSE.

Contributing

Issues and pull requests welcome. Adversarial reviews especially — prior releases went through 11 rounds of external review before shipping.