Purpose mcp-macos is an MCP server for AI Agents, used to observe and operate the macOS system. It encapsulates capabilities on the Mac such as files, processes, apps, Shell, AppleScript, and GUI as MCP tools, while controlling risk through a strict tiered permission model. This project belongs to dockndevai's MCP server suite and shares the same governance model.
Main capabilities Divided into three tiers by capability. Read-only tier: read files, list processes and apps, take screenshots. Read-write tier: write files, set the clipboard, send notifications, open projects. Administrator tier (requires explicit enablement): run commands, run AppleScript, delete to Trash, kill processes, drive the GUI. The server defaults to read-only at startup; higher-privilege tools are only registered after elevated mode; each high-impact capability requires both administrator mode and its own independent switch, and the most dangerous operations require human approval for every call.
Usage Requires macOS and Node ≥ 22. click and move_mouse depend on cliclick, which can be installed via brew install cliclick. The project provides docs/CLIENTS.md, containing configuration snippets for Claude Code, Cursor, Codex, VS Code, and Windsurf; for environment variables, refer to .env.example. The security model is enforced by src/security.ts, see SECURITY.md for details.
macOS permissions The host process (terminal or MCP client) needs to be granted the following permissions in "System Settings → Privacy & Security": Screen Recording (for screenshot), Accessibility (for type_text, key_press, click, move_mouse), Automation (prompted per app, for run_applescript and app control), Files and Folders/Full Disk Access (for reading and writing outside the default sandbox). You will be prompted to grant them when first needed; permissions that are not granted cannot be bypassed.
Applicable scenarios and limitations Suitable for scenarios where an Agent needs to perform observation and controlled operations on a Mac, especially use cases that want read-only by default, on-demand privilege escalation, and a retained human approval step. Limitations include: macOS only; requires Node 22 or above; high-risk capabilities require manually enabling multiple switches and mayrequire human approval for each call; when the corresponding macOS privacy permissions are not granted, the related tools cannot work. The project does not provide other information about charges, pricing, or platforms beyond this, and none is currently provided.
