dockndevai/mcp-macos

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
Requires **macOS** and **Node ≥ 22**. click/move_mouse also need cliclick (brew install cliclick).
Configure
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). |