mcp-macos

npm licence

A safe-by-default Model Context Protocol server that lets an agent observe and operate a Mac — read files, list processes and apps, take screenshots (read-only); write files, set the clipboard, post notifications, open things (read-write); and, behind explicit opt-ins, run commands / AppleScript, delete to Trash, kill processes and drive the GUI (admin).

It starts read-only. Every high-impact power needs both admin mode and its own flag, and the most dangerous ones ask the human to approve each call. Part of the dockndevai MCP server suite — one governance model across all of them.

Pure Node + osascript/screencapture — no native add-ons. macOS only.

What it gives an agent

The server starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.

Tool	For	Needs mode
`system_info`	macOS version, hardware, memory, load, uptime	read-only
`list_directory` / `read_file`	browse & read files (path-allowlisted)	read-only
`list_processes`	running processes by CPU/mem	read-only
`get_clipboard`	read the clipboard	read-only
`list_apps` / `get_frontmost_app`	running apps; the active one	read-only
`screenshot`	capture the screen as a PNG	read-only
`write_file`	create/overwrite a file (confirms on overwrite)	read-write
`set_clipboard` / `notify` / `open`	set clipboard, notify, open a file/URL/app	read-write
`run_command`	run a program (argv, no shell)	admin + `MACOS_ALLOW_EXEC`
`run_applescript`	run AppleScript / JXA	admin + `MACOS_ALLOW_EXEC`
`kill_process`	signal a process	admin + `MACOS_ALLOW_EXEC`
`delete_path`	move a path to the Trash	admin + `MACOS_ALLOW_DELETE`
`type_text` / `key_press` / `click` / `move_mouse`	drive the GUI	admin + `MACOS_ALLOW_INPUT`

Install

npx -y @dockndevai/mcp-macos

Requires macOS and Node ≥ 22. click/move_mouse also need cliclick (brew install cliclick).

Configure

{
  "mcpServers": {
    "macos": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-macos"],
      "env": {
        "MACOS_MODE": "read-only"
      }
    }
  }
}

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.

Safe by default

This server can drive an entire Mac, so the access model (enforced by src/security.ts) is deliberately strict — defence in depth, not documentation:

Question	Setting	Default	Notes
What can it do at all?	`MACOS_MODE`	`read-only`	`read-only` observes; `read-write` writes files/clipboard/opens; `admin` adds exec/delete/kill/GUI. Tools above the mode are never registered.
Which paths can it touch?	`MACOS_PATH_ALLOWLIST`	(anywhere)	Comma-separated roots. When set, any file op outside them is refused.
Which paths are read-only forever?	`MACOS_PROTECTED_PATHS`	system + secrets	`/System`, `/usr`, `/bin`, `/sbin`, `/private`, `/Library`, `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/Library/Keychains` — readable, never mutated.
Can it run commands?	`MACOS_ALLOW_EXEC`	`false`	Gates `run_command`, `run_applescript`, `kill_process` (on top of admin).
Restrict which programs?	`MACOS_COMMAND_ALLOWLIST`	(any)	When set, `run_command` may only invoke these program names.
Can it delete?	`MACOS_ALLOW_DELETE`	`false`	Gates `delete_path` (moves to the Trash, recoverable).
Can it drive the GUI?	`MACOS_ALLOW_INPUT`	`false`	Gates `type_text`/`key_press`/`click`/`move_mouse`.
Preview without doing	`MACOS_DRY_RUN`	`false`	Mutating tools validate + log intent, then return.
Audit trail	`MACOS_AUDIT_LOG`	`true`	JSON line to stderr per guarded operation (`ALLOW`/`DENY`/`DRY_RUN`).
Interactive confirmation	(automatic)	—	`run_command`, `run_applescript`, `delete_path`, `kill_process` and file overwrites ask the human to approve via MCP elicitation before running; clients without elicitation fall back to the flags.

See SECURITY.md.

macOS permissions

The host process (your terminal / MCP client) must be granted, in System Settings → Privacy & Security:

Screen Recording — for screenshot.
Accessibility — for type_text / key_press / click / move_mouse.
Automation (per-app prompts) — for run_applescript and app control.
Files and Folders / Full Disk Access — to read/write outside the default sandbox.

You'll be prompted the first time each is needed; nothing works around a permission you haven't granted.

Developing

npm install
npm run build
MACOS_MODE=read-only node dist/index.js
# introspect the tool list:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Licence

MIT