Skip to main content
Glama
Sign In
mcp-mac-control

mcp-mac-control

by dockndevai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: mcp-macos-cua

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 → run_command, run_applescript, delete_path, kill_process pause for human approval via MCP elicitation. The prompt shows the tool, the exact arguments (command text, script, path) and a fingerprint; for delete_path, kill_process and file overwrites the target's version is pinned across the prompt and the action is refused if it changed; a prompt nobody answers is a refusal; trashing a folder also needs its path typed

MACCTL_REQUIRE_HUMAN_APPROVAL

false

true → implies MACCTL_CONFIRM, and those actions are refused if the client cannot elicit (instead of running on the MACCTL_ALLOW_* flags alone)

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

Available Tools

26 tools
activate_appActivate (focus) an appA

Bring an application to the front (launching it if needed) so subsequent clicks/keystrokes go to it. Give the app's name, e.g. 'Safari', 'Notes'.

Inputs: name (required).

clickClickA

Click at screen coordinates. Requires admin mode AND MACCTL_ALLOW_INPUT=true, and the cliclick tool (brew install cliclick).

Inputs: x (required), y (required), button.

delete_pathDelete a path (to Trash)A
Destructive

Move a file or folder to the Trash (recoverable). Requires admin mode AND MACCTL_ALLOW_DELETE=true. Honours the path allowlist and refuses protected paths.

Inputs: path (required).

dragDragA

Press at (x1,y1), move to (x2,y2), and release — a human-style drag (select text, move a window, drag a file). Requires admin mode AND MACCTL_ALLOW_INPUT=true, and the cliclick tool.

Inputs: x1 (required), x2 (required), y1 (required), y2 (required).

get_clipboardRead the clipboardA
Read-onlyIdempotent

Return the current text contents of the macOS clipboard.

Inputs: no named parameters.

get_frontmost_appFrontmost appA
Read-onlyIdempotent

Return the name of the frontmost (active) application.

Inputs: no named parameters.

get_screen_sizeScreen sizeA
Read-onlyIdempotent

Return the overall desktop size AND every display's global point bounds (origin x/y, width, height, scale, main) — use it to reason about click coordinates across monitors.

Inputs: no named parameters.

key_pressPress a keyA

Press a key (e.g. return, tab, escape, arrows, or a character) with optional modifiers (command/option/control/shift). Requires admin mode AND MACCTL_ALLOW_INPUT=true.

Inputs: key (required), modifiers.

kill_processKill a processA
Destructive

Send a signal (default SIGTERM) to a process by pid. Requires admin mode AND MACCTL_ALLOW_EXEC=true.

Inputs: pid (required), signal.

list_appsList running appsA
Read-onlyIdempotent

List the names of currently running (non-background) applications.

Inputs: no named parameters.

list_directoryList a directoryA
Read-onlyIdempotent

List the entries (name, type, size) of a directory. Honours the path allowlist.

Inputs: path (required).

list_processesList processesA
Read-onlyIdempotent

List running processes (pid, cpu%, mem%, command), busiest first.

Inputs: limit, filter.

list_windowsList windowsA
Read-onlyIdempotent

List the windows of the frontmost app with each window's name, position and size — so you can click or drag reliably. Needs Accessibility permission for the host process.

Inputs: no named parameters.

move_mouseMove the mouseA

Move the cursor to screen coordinates. Requires admin mode AND MACCTL_ALLOW_INPUT=true (cliclick).

Inputs: x (required), y (required).

notifyShow a notificationA

Post a macOS notification with a title and message.

Inputs: title (required), message (required).

openOpen a file, URL or appA

Open a file/folder path or URL with its default handler, or launch an app by name (set app=true).

Inputs: target (required), app.

quit_appQuit an appA

Ask an application to quit (graceful). Unsaved changes may prompt inside the app. Give the app's name.

Inputs: name (required).

read_fileRead a fileA
Read-onlyIdempotent

Read a text file's contents (capped at MACCTL_MAX_FILE_BYTES). Honours the path allowlist.

Inputs: path (required).

run_applescriptRun AppleScript / JXAA
Destructive

Run an AppleScript (or JavaScript for Automation) snippet via osascript. Powerful — can drive any scriptable app. Requires admin mode AND MACCTL_ALLOW_EXEC=true.

Inputs: script (required), language.

run_commandRun a commandA
Destructive

Run a program with arguments (no shell — pass argv, not a command line). Requires admin mode AND MACCTL_ALLOW_EXEC=true; the program must be in MACCTL_COMMAND_ALLOWLIST when that is set. For a shell pipeline, run command="zsh", args=["-c","…"].

Inputs: command (required), cwd, args.

screenshotScreenshotA
Read-onlyIdempotent

Capture a display as a PNG and return it. The image is downscaled to POINTS, so it is 1:1 with click coordinates. Omit display to capture the display holding the frontmost window (handy with a second monitor); pass 0 for the main display. Needs Screen Recording permission.

Inputs: display.

scrollScrollA

Scroll the mouse wheel in a direction by a number of lines (over whatever is under the cursor / frontmost). Requires admin mode AND MACCTL_ALLOW_INPUT=true.

Inputs: direction (required), amount.

set_clipboardSet the clipboardA

Replace the macOS clipboard contents with the given text.

Inputs: text (required).

system_infoSystem infoA
Read-onlyIdempotent

Report macOS version, hardware, memory, load, uptime and the current user.

Inputs: no named parameters.

type_textType textA

Type literal text into the frontmost app (keystrokes). Requires admin mode AND MACCTL_ALLOW_INPUT=true, plus Accessibility permission for the host process.

Inputs: text (required).

write_fileWrite a fileA

Create or overwrite a text file. Honours the path allowlist, refuses protected paths, and asks for confirmation before overwriting an existing file.

Inputs: path (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools target clearly distinct actions and resources, so an agent can generally pick the right one. The main ambiguity is between open (with app=true) and activate_app for launching apps, and run_command vs run_applescript overlap in arbitrary execution.

    Naming Consistency4/5

    The set mostly follows predictable verb_prefix patterns: list_*, get_*, read/write, run_*, and *_app. A few bare verbs like screenshot, notify, open, click, and scroll, plus system_info as a noun, break strict consistency but the groups remain readable.

    Tool Count4/5

    26 tools is on the heavy end, but the server's domain—macOS UI automation, file access, process control, clipboard, apps, and system info—is genuinely broad. Each tool has an identifiable purpose and none feel redundant.

    Completeness4/5

    The surface covers the core macOS automation lifecycle: inspect, interact, input, file read/write/delete, process list/kill, app management, clipboard, and notifications. Minor gaps exist such as no directory creation, no file copy/move, and no arbitrary window picker, but agents can work around these.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Automation MCP

      ashwwwin
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.
      10 npm
      415
      MIT

    • mcp-macos-cua

      bradthebeeble
      A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to control macOS desktop apps via screenshots, mouse clicks, keyboard input, accessibility queries, and AppleScript.
      11
      12 npm
      MIT

    • gemini-mac-computer-use-mcp

      Be-Young
      F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control macOS by capturing screenshots and performing mouse clicks, movement, dragging, text typing, hotkeys, and scrolling, with support for Gemini's normalized coordinate protocol and Retina display scaling.
      -

    • control-mouse-mac-mcp

      wwwang176
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI MCP clients to control macOS through screenshots, mouse clicks, scrolling and dragging, Unicode keyboard input and shortcuts, clipboard access, and window management, with multi-monitor and Retina coordinate handling plus visual action feedback.
      MIT