Mcp Macos

io.github.dockndevaiPublished by GitHub account dockndevaiv0.2.1Updated Nov 4, 2026

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

VerifiedSTDIODesktop onlyBrowser AutomationFiles & StorageDeveloper Tools

Overview

AI-generated overview

Local MCP server that lets an AI assistant observe and operate a Mac — files, processes, apps, screenshots, shell, AppleScript and GUI — read-only by default.

What you can do
  • Inspect the system: macOS version, hardware, memory, load, uptime, running processes and apps, frontmost app.
  • Browse and read files within an allowlist, and read the clipboard.
  • Capture the screen as a PNG.
  • Write files, set the clipboard, post notifications, and open files, URLs or apps (read-write mode).
  • Run programs, AppleScript/JXA and signal processes (admin plus exec flag).
  • Move paths to the Trash, and drive the GUI with typing, key presses, clicks and mouse moves (admin plus their own flags).
When to use it
Useful when an assistant needs to inspect or act on the local Mac: checking system state, reading project files, taking screenshots, or automating apps and the desktop. The tiered modes let you start with observation only and raise capability deliberately.
Requirements
macOS only, with Node 22 or newer; runs locally via npx. Screen Recording, Accessibility, Automation and Files and Folders/Full Disk Access permissions must be granted to the host terminal or MCP client. Clicks and mouse moves also need the cliclick utility. Configured through environment variables such as MACOS_MODE, MACOS_PATH_ALLOWLIST, MACOS_ALLOW_EXEC, MACOS_ALLOW_DELETE and MACOS_ALLOW_INPUT.
Before you install
Admin mode plus the exec, delete and input flags let the assistant run commands and AppleScript, kill processes, delete to Trash and control the GUI — grant them only when needed. Path allowlist defaults to anywhere, though protected paths such as ~/.ssh, ~/.aws and keychains stay read-only. High-impact calls ask the human to approve via elicitation, but clients without elicitation fall back to the flags alone. Audit lines go to stderr.

Installation

In SourceWeft

  1. Open Mcp Macos in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-macos

[npm] [CI] [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.

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

bash
npx -y @dockndevai/mcp-macos

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

Configure

json
{  "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

bash
npm installnpm run buildMACOS_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

Source: README.md at commit 8c76767

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.2.1LatestOct 14, 2026
  2. v0.2.0Sep 29, 2026
  3. v0.1.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts