How do I install Macos?

Macos is a local plugin. Install it using npm package: @dockndevai/mcp-macos and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

Is Macos safe to use?

Macos scored 6/10 (moderate risk) in MCP Marketplace's automated security scan. It has 1 high or critical finding to review. It's listed, but review the security report on this page before installing.

What credentials does Macos need?

Macos requires the following credentials or environment variables: MACOS_MODE, MACOS_ALLOW_EXEC, MACOS_ALLOW_DELETE, MACOS_ALLOW_INPUT, MACOS_PATH_ALLOWLIST. You can find setup instructions on the server detail page.

What AI apps work with Macos?

Macos uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Macos MCP Server

by dockndevai

Developer ToolsModerate6.0Local

Free

Observe & operate a Mac — files, processes, apps, shell, AppleScript, GUI — safe by default.

About

Observe & operate a Mac — files, processes, apps, shell, AppleScript, GUI — safe by default.

Security Report

6.0

Moderate6.0Moderate Risk

This macOS automation server is strongly gated: it starts read-only, admin tools are unregistered unless the mode is raised, and exec, delete and input each need their own opt-in flag plus human confirmation. The main concerns are in the command allowlist, which checks only the basename of the program and can be bypassed by a full path or a zsh -c wrapper, and in run_command's working directory, which is not checked against the path allowlist. Supply chain analysis found 1 known vulnerability in dependencies (0 critical, 1 high severity). Package verification found 1 issue.

7 files analyzed · 9 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

What You'll Need

Set these up before or after installing:

Access mode: read-only | read-write | admin. Starts read-only; writes need read-write.Optional

Environment variable: MACOS_MODE

Set true to allow run_command / run_applescript / kill_process (admin mode).Optional

Environment variable: MACOS_ALLOW_EXEC

Set true to allow delete_path (moves to Trash; admin mode).Optional

Environment variable: MACOS_ALLOW_DELETE

Set true to allow GUI input (type/key/click; admin mode). Needs Accessibility permission.Optional

Environment variable: MACOS_ALLOW_INPUT

Comma-separated path roots the agent may touch (empty = anywhere; protected paths still apply).Optional

Environment variable: MACOS_PATH_ALLOWLIST

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "io-github-dockndevai-mcp-macos": {
      "env": {
        "MACOS_MODE": "your-macos-mode-here",
        "MACOS_ALLOW_EXEC": "your-macos-allow-exec-here",
        "MACOS_ALLOW_INPUT": "your-macos-allow-input-here",
        "MACOS_ALLOW_DELETE": "your-macos-allow-delete-here",
        "MACOS_PATH_ALLOWLIST": "your-macos-path-allowlist-here"
      },
      "args": [
        "-y",
        "@dockndevai/mcp-macos"
      ],
      "command": "npx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

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

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