Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
<p align="center"> <img src="docs/demo.gif" width="720" alt="mac-control-mcp driving Safari: open tab, type query, capture window, OCR, Spotlight search — all via MCP stdio"> </p>
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:
- Download mac-control-mcp-v0.2.6.mcpb from the release page.
- Double-click the
.mcpbfile. Claude Desktop opens an install dialog. - Click Install. The server is registered under the name
mac-control-mcpand available immediately in new chats. - 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:
- Download MacControlMCP-v0.2.6-macos-universal.tar.gz.
- Extract and move
MacControlMCP.appto~/Applications/. - 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.6-macos-universal.tar.gz
# should match MacControlMCP-v0.2.6-macos-universal.sha256 on the release3. 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.shProduces ~/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 "[email protected]" --team-id "XXXXXXXXXX"
# subsequent builds:
NOTARIZE_PROFILE=mac-control-mcp ./scripts/build-bundle.shTool surface
| Category | Tools |
|---|---|
| Permissions | permissions_status, request_permissions |
| Accessibility | find_element(s), query_elements, list_elements, get_ui_tree, get_element_attributes, set_element_attribute, read_value, perform_element_action, wait_for_element, scroll_to_element |
| App lifecycle | list_apps, launch_app, activate_app, quit_app, force_quit_app, wait_for_app, focused_app |
| Windows | list_windows, focus_window, move_window, resize_window, set_window_state, wait_for_window, move_window_to_display |
| Input | click, mouse_event, drag_and_drop, scroll, type_text, press_key, press_key_sequence, key_down, key_up, convert_coordinates |
| Menus | click_menu_path, list_menu_paths, list_menu_titles |
| Browser | browser_list_tabs, browser_get_active_tab, browser_navigate, browser_new_tab, browser_close_tab, browser_eval_js |
| Screen | capture_screen, capture_window, capture_display, ocr_screen |
| Clipboard | clipboard_read, clipboard_write, clipboard_clear |
| Spotlight | spotlight_search, spotlight_open_result |
| System | set_volume, set_dark_mode, list_displays |
| File dialogs | file_dialog_set_path, file_dialog_select_item, file_dialog_confirm, file_dialog_cancel, wait_for_file_dialog |
Total: 63 tools.
Security model
- Tools that write files (
capture_*,ocr_screen) validateoutput_pathvia a strict allow-list — only the user-scoped temp dir (NSTemporaryDirectory()) and~/Desktop,~/Documents,~/Downloads,~/Picturesare accepted. Symlinks at the target path are rejected to prevent redirection./tmpis deliberately excluded because it's shared across users and opens a TOCTOU window. - AppleScript string interpolation for
browser_eval_jswraps user code in(0, eval)(…)viaJSON.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)
| Scope | State |
|---|---|
| Unit / integration test suite | 63 tests in 11 suites, all green locally and on CI (macos-15) |
| Live tool probe | 43 of the 63 tools exercised end-to-end via real MCP stdio against the running binary, all pass |
| Destructive tools (volume, dark mode, force_quit_app, drag_and_drop, file_dialog_*) | Verified live in a reversible way |
| Code signing | Developer ID Application (A3W973JZ49) with hardened runtime |
| Apple notarization | Accepted by Apple Notary Service, ticket stapled, spctl reports source=Notarized Developer ID |
| Gatekeeper flow | Extracted + launched with the com.apple.quarantine xattr set; no right-click-open needed |
| MCP Registry | Published as io.github.AdelElo13/mac-control-mcp v0.2.6 — distributed as an .mcpb bundle for one-click install |
| Architectures | Universal binary (arm64 + x86_64). Intel slice compiles cleanly but has not been runtime-verified on actual Intel hardware |
move_window_to_display | Skipped — requires a 2+ display setup |
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.plistmake 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 includedLicense
MIT — see LICENSE.
Contributing
Issues and pull requests welcome. Adversarial reviews especially — prior releases went through 11 rounds of external review before shipping.