English Français العربية

io.github.dockndevai/mcp-mac-control

Official registry Productivity

Full macOS control — drive a Mac like a human: shell, AppleScript, files, and human-like GUI.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @dockndevai/mcp-mac-control
Claude Code 
claude mcp add mcp-mac-control -e 'MACCTL_SAFE_MODE=<MACCTL_SAFE_MODE>' -e 'MACCTL_MODE=<MACCTL_MODE>' -e 'MACCTL_CONFIRM=<MACCTL_CONFIRM>' -e 'MACCTL_PATH_ALLOWLIST=<MACCTL_PATH_ALLOWLIST>' -e 'MACCTL_PROTECTED_PATHS=<MACCTL_PROTECTED_PATHS>' -- npx -y @dockndevai/mcp-mac-control@0.3.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "mcp-mac-control": {
            "command": "npx",
            "args": [
                "-y",
                "@dockndevai/mcp-mac-control@0.3.1"
            ],
            "env": {
                "MACCTL_SAFE_MODE": "<MACCTL_SAFE_MODE>",
                "MACCTL_MODE": "<MACCTL_MODE>",
                "MACCTL_CONFIRM": "<MACCTL_CONFIRM>",
                "MACCTL_PATH_ALLOWLIST": "<MACCTL_PATH_ALLOWLIST>",
                "MACCTL_PROTECTED_PATHS": "<MACCTL_PROTECTED_PATHS>"
            }
        }
    }
}

Environment variables

  • MACCTL_SAFE_MODE Set true to invert to safe-by-default: read-only, all powers gated, confirmations on. Default false (full control).
  • MACCTL_MODE Access mode: read-only | read-write | admin. Defaults to admin (or read-only in safe mode).
  • MACCTL_CONFIRM Set true to require human approval (via MCP elicitation) on destructive ops. Default off in full control.
  • MACCTL_PATH_ALLOWLIST Comma-separated path roots the agent may touch (empty = anywhere).
  • MACCTL_PROTECTED_PATHS Comma-separated path roots that may be read but never modified/deleted (empty by default in full control).

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. mcp-mac-control
  2. What it gives an agent (26 tools)
  3. Install
  4. Configure (Claude Code)
  5. Dialing the control up or down
  6. AI risk guard (optional)
  7. Developing
  8. Licence

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:

VariableDefaultEffect
MACCTL_SAFE_MODEfalsetrue → read-only, every power gated, confirmations on (safe-by-default)
MACCTL_MODEadminread-only / read-write / admin — caps which tools are registered
MACCTL_ALLOW_EXECtrueshell / AppleScript / kill
MACCTL_ALLOW_DELETEtruedelete to Trash
MACCTL_ALLOW_INPUTtrueGUI input (mouse/keyboard)
MACCTL_CONFIRMfalsetrue → 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_RUNfalsevalidate + log writes without executing
MACCTL_AUDIT_LOGtrueJSON 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.

VariableDefaultEffect
MACCTL_GUARD_MODEoffmonitor (log what it would do) / enforce (block or require confirm)
MACCTL_GUARD_URLhttp://127.0.0.1:8799the local laya-guard daemon
MACCTL_GUARD_TIMEOUT_MS2000per-check timeout
MACCTL_GUARD_FAIL_CLOSEDconfirmwhen 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

Frequently asked questions

What is io.github.dockndevai/mcp-mac-control?

Full macOS control — drive a Mac like a human: shell, AppleScript, files, and human-like GUI.

How do I install io.github.dockndevai/mcp-mac-control?

It runs on your machine. In Claude Code: claude mcp add mcp-mac-control -e 'MACCTL_SAFE_MODE=<MACCTL_SAFE_MODE>' -e 'MACCTL_MODE=<MACCTL_MODE>' -e 'MACCTL_CONFIRM=<MACCTL_CONFIRM>' -e 'MACCTL_PATH_ALLOWLIST=<MACCTL_PATH_ALLOWLIST>' -e 'MACCTL_PROTECTED_PATHS=<MACCTL_PROTECTED_PATHS>' -- npx -y @dockndevai/mcp-mac-control@0.3.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.dockndevai/mcp-mac-control need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.dockndevai/mcp-mac-control open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.dockndevai/mcp-mac-control?

It is published by dockndevai. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.