Mcp Mac Control

io.github.dockndevaiPublished by GitHub account dockndevaiv0.3.1Updated Nov 3, 2026

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

VerifiedSTDIODesktop onlyBrowser AutomationFiles & StorageDeveloper Tools

Overview

AI-generated overview

Local MCP server that gives an AI agent full control of a Mac: shell commands, AppleScript, files, processes and human-like mouse and keyboard GUI input.

What you can do
  • Perceive the machine: take screenshots, read screen size, list windows, apps and processes, inspect the frontmost app, read files and directories, get system info and clipboard.
  • Operate the desktop like a person: move, click, double/right-click, drag, scroll, type text, press key combos, activate or quit apps, open items, set the clipboard and show notifications.
  • Run full-power actions: execute arbitrary commands, run AppleScript/JXA, delete paths to the Trash and kill processes.
  • Write files and follow a screenshot, act, screenshot loop for GUI automation.
When to use it
Use it when an agent should drive a Mac end to end, for example automating a GUI-only app, reproducing a desktop workflow, or combining shell, AppleScript and mouse/keyboard actions on a machine you control. It is not a good fit if you only need read-only inspection or a safer default posture.
Requirements
macOS only, run locally via npx from the npm package. The host app needs macOS Screen Recording (screenshots), Accessibility (GUI input, window listing) and Automation (AppleScript/app control) permissions. Mouse control requires cliclick installed via Homebrew. Optional laya-guard daemon for the AI risk guard.
Before you install
Full control by default: admin mode with command execution, deletes and GUI input enabled, and no confirmation unless MACCTL_CONFIRM is set. Anything the agent reads could carry a prompt injection that runs arbitrary code on the Mac. Restrict with MACCTL_SAFE_MODE, MACCTL_MODE, the allow/protect path and command lists, and dry-run; audit lines go to stderr by default.

Installation

In SourceWeft

  1. Open Mcp Mac Control in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-mac-control

[npm] [CI] [licence]

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

bash
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)

bash
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

bash
npm installnpm run buildecho '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js   # list toolsnpm test

Licence

MIT

Source: README.md at commit ff6e364

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.3.1LatestSep 26, 2026
  2. v0.2.1Sep 19, 2026
  3. v0.1.0Sep 17, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts