mcp-mac-control

mcp-mac-control

A Model Context Protocol server that gives an AI agent full control of a Mac — like a person sitting at it. Shell, AppleScript, files, processes, and human-like GUI control: move, click, double/right-click, drag, scroll, type, and press key combos — with a screenshot + window/screen-size perception loop.

⚠️ This server is full-control by default. It starts in admin mode with command execution, deletes, and GUI input all enabled. That is powerful and dangerous: anything the agent reads (a web page, an email, a file) could contain a prompt injection that then runs arbitrary code on your Mac. Only connect it to an agent and content you trust. Set MACCTL_SAFE_MODE=true to flip the whole thing to safe-by-default. If you want safe-by-default as the baseline, use the sibling @dockndevai/mcp-macos instead.

Part of the dockndevai MCP server suite.

What it gives an agent (26 tools)

Perceive — screenshot, get_screen_size, list_windows, get_frontmost_app, list_apps, system_info, list_directory, read_file, list_processes, get_clipboard

Operate the desktop like a human — move_mouse, click (left/right/double), drag, scroll, type_text, key_press (with ⌘/⌥/⌃/⇧), activate_app, quit_app, open, set_clipboard, notify, write_file

Full power — run_command (any program, no shell unless you ask for one), run_applescript (AppleScript/JXA — drive any scriptable app), delete_path (→ Trash), kill_process

The classic loop: screenshot → decide → click/type/drag/scroll → screenshot again.

Install

npx -y @dockndevai/mcp-mac-control

macOS only. You'll need to grant the host app (Terminal, your IDE, Claude Desktop, …) macOS permissions the first time each capability is used:

• Screen Recording → for screenshot
• Accessibility → for GUI input (click, type_text, drag, scroll, key_press) and list_windows
• Automation → for AppleScript / app control
• Mouse control uses cliclick: brew install cliclick

Configure (Claude Code)

claude mcp add mac-control -- npx -y @dockndevai/mcp-mac-control

That's it — it's full-control by default. To scope it down, add env flags (see below). See docs/CLIENTS.md for Claude Desktop / Cursor / Codex / VS Code / Windsurf, and .env.example for every variable.

Dialing the control up or down

Full control needs no configuration. Everything below is about restricting it:

Variable	Default	Effect
MACCTL_SAFE_MODE	false	true → read-only, every power gated, confirmations on (safe-by-default)
MACCTL_MODE	admin	read-only / read-write / admin — caps which tools are registered
MACCTL_ALLOW_EXEC	true	shell / AppleScript / kill
MACCTL_ALLOW_DELETE	true	delete to Trash
MACCTL_ALLOW_INPUT	true	GUI input (mouse/keyboard)
MACCTL_CONFIRM	false	true → destructive ops pause for human approval via MCP elicitation
MACCTL_PATH_ALLOWLIST	(empty = anywhere)	confine file ops to these roots
MACCTL_PROTECTED_PATHS	(empty)	roots readable but never modified/deleted
MACCTL_COMMAND_ALLOWLIST	(empty = any)	restrict run_command to these programs
MACCTL_DRY_RUN	false	validate + log writes without executing
MACCTL_AUDIT_LOG	true	JSON audit line per guarded op, to stderr

The policy engine (src/security.ts) is the same graduated model as the rest of the suite — this server just ships it wide open by default. See SECURITY.md.

AI risk guard (optional)

For an extra layer on top of the static rules, this server can consult a local laya-guard daemon before running a high-risk tool (run_command, run_applescript, delete_path). The guard classifies the actual command — deterministic patterns plus a local decision model — as allow / confirm / block. It runs after the deterministic policy and can only tighten (add a confirm or block), never grant.

Variable	Default	Effect
MACCTL_GUARD_MODE	off	monitor (log what it would do) / enforce (block or require confirm)
MACCTL_GUARD_URL	http://127.0.0.1:8799	the local laya-guard daemon
MACCTL_GUARD_TIMEOUT_MS	2000	per-check timeout
MACCTL_GUARD_FAIL_CLOSED	confirm	when the daemon is unreachable in enforce mode: confirm or allow

Run the daemon with pipx install laya-guard && laya-guard. Start in monitor to see what it catches, then switch to enforce.

Developing

npm install
npm run build
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js   # list tools
npm test

Licence

MIT