English Français العربية

io.github.dockndevai/mcp-macos

Official registry Other

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

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @dockndevai/mcp-macos
Claude Code 
claude mcp add mcp-macos -e 'MACOS_MODE=<MACOS_MODE>' -e 'MACOS_ALLOW_EXEC=<MACOS_ALLOW_EXEC>' -e 'MACOS_ALLOW_DELETE=<MACOS_ALLOW_DELETE>' -e 'MACOS_ALLOW_INPUT=<MACOS_ALLOW_INPUT>' -e 'MACOS_PATH_ALLOWLIST=<MACOS_PATH_ALLOWLIST>' -- npx -y @dockndevai/mcp-macos@0.2.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "mcp-macos": {
            "command": "npx",
            "args": [
                "-y",
                "@dockndevai/mcp-macos@0.2.1"
            ],
            "env": {
                "MACOS_MODE": "<MACOS_MODE>",
                "MACOS_ALLOW_EXEC": "<MACOS_ALLOW_EXEC>",
                "MACOS_ALLOW_DELETE": "<MACOS_ALLOW_DELETE>",
                "MACOS_ALLOW_INPUT": "<MACOS_ALLOW_INPUT>",
                "MACOS_PATH_ALLOWLIST": "<MACOS_PATH_ALLOWLIST>"
            }
        }
    }
}

Environment variables

  • MACOS_MODE Access mode: read-only | read-write | admin. Starts read-only; writes need read-write.
  • MACOS_ALLOW_EXEC Set true to allow run_command / run_applescript / kill_process (admin mode).
  • MACOS_ALLOW_DELETE Set true to allow delete_path (moves to Trash; admin mode).
  • MACOS_ALLOW_INPUT Set true to allow GUI input (type/key/click; admin mode). Needs Accessibility permission.
  • MACOS_PATH_ALLOWLIST Comma-separated path roots the agent may touch (empty = anywhere; protected paths still apply).

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. mcp-macos
  2. What it gives an agent
  3. Install
  4. Configure
  5. Safe by default
  6. macOS permissions
  7. Developing
  8. Licence

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.

ToolForNeeds mode
system_infomacOS version, hardware, memory, load, uptimeread-only
list_directory / read_filebrowse & read files (path-allowlisted)read-only
list_processesrunning processes by CPU/memread-only
get_clipboardread the clipboardread-only
list_apps / get_frontmost_apprunning apps; the active oneread-only
screenshotcapture the screen as a PNGread-only
write_filecreate/overwrite a file (confirms on overwrite)read-write
set_clipboard / notify / openset clipboard, notify, open a file/URL/appread-write
run_commandrun a program (argv, no shell)admin + MACOS_ALLOW_EXEC
run_applescriptrun AppleScript / JXAadmin + MACOS_ALLOW_EXEC
kill_processsignal a processadmin + MACOS_ALLOW_EXEC
delete_pathmove a path to the Trashadmin + MACOS_ALLOW_DELETE
type_text / key_press / click / move_mousedrive the GUIadmin + 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:

QuestionSettingDefaultNotes
What can it do at all?MACOS_MODEread-onlyread-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_PATHSsystem + secrets/System, /usr, /bin, /sbin, /private, /Library, ~/.ssh, ~/.aws, ~/.gnupg, ~/Library/Keychains — readable, never mutated.
Can it run commands?MACOS_ALLOW_EXECfalseGates 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_DELETEfalseGates delete_path (moves to the Trash, recoverable).
Can it drive the GUI?MACOS_ALLOW_INPUTfalseGates type_text/key_press/click/move_mouse.
Preview without doingMACOS_DRY_RUNfalseMutating tools validate + log intent, then return.
Audit trailMACOS_AUDIT_LOGtrueJSON 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

Frequently asked questions

What is io.github.dockndevai/mcp-macos?

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

How do I install io.github.dockndevai/mcp-macos?

It runs on your machine. In Claude Code: claude mcp add mcp-macos -e 'MACOS_MODE=<MACOS_MODE>' -e 'MACOS_ALLOW_EXEC=<MACOS_ALLOW_EXEC>' -e 'MACOS_ALLOW_DELETE=<MACOS_ALLOW_DELETE>' -e 'MACOS_ALLOW_INPUT=<MACOS_ALLOW_INPUT>' -e 'MACOS_PATH_ALLOWLIST=<MACOS_PATH_ALLOWLIST>' -- npx -y @dockndevai/mcp-macos@0.2.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.dockndevai/mcp-macos need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.dockndevai/mcp-macos open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.dockndevai/mcp-macos?

It is published by dockndevai. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.