{"_id":"@dockndevai/mcp-macos","_rev":"3-8a264d21000a2c3567ad98da001fed34","name":"@dockndevai/mcp-macos","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@dockndevai/mcp-macos","version":"0.1.0","keywords":["mcp","model-context-protocol","macos","mac","automation","applescript","computer-use","llm","ai"],"license":"MIT","_id":"@dockndevai/mcp-macos@0.1.0","maintainers":[{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"}],"homepage":"https://github.com/dockndevai/mcp-macos#readme","bugs":{"url":"https://github.com/dockndevai/mcp-macos/issues"},"os":["darwin"],"bin":{"mcp-macos":"dist/index.js"},"dist":{"shasum":"6b34415a84db521fe628203651b0dcc46b24700a","tarball":"https://registry.npmjs.org/@dockndevai/mcp-macos/-/mcp-macos-0.1.0.tgz","fileCount":36,"integrity":"sha512-No4yIJLzJYfeJX7xJe7gDEzKiXSGzNaR+GLreeOtiEZhyoyNQdt4IfTKaavz2/eR69qdrBn5GKwkbA/Su1dwCA==","signatures":[{"sig":"MEQCIHqIn624K74IDJ7dZ3tV+QJH1xnQ59dPWJURw1VMD2sNAiBn1neg/UBhCD4dcvcWhei/EAiYCedHCKbfimNeZOiZCg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dockndevai%2fmcp-macos@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":106103},"type":"module","engines":{"node":">=22"},"gitHead":"5614a5f5fa54215a75ec22c46e06d9254152b9b8","mcpName":"io.github.dockndevai/mcp-macos","scripts":{"dev":"tsx watch src/index.ts","lint":"tsc -p tsconfig.json --noEmit","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"},"repository":{"url":"git+https://github.com/dockndevai/mcp-macos.git","type":"git"},"_npmVersion":"10.9.8","description":"Model Context Protocol server for macOS — observe and operate a Mac (files, processes, apps, screenshots, shell, AppleScript, GUI) with safe-by-default access controls.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.5.4","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","vitest":"^5.0.0","typescript":"^7.0.2","@types/node":"^22.9.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-macos_0.1.0_1789056444141_0.4094445902261843","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@dockndevai/mcp-macos","version":"0.1.1","keywords":["mcp","model-context-protocol","macos","mac","automation","applescript","computer-use","llm","ai"],"license":"MIT","_id":"@dockndevai/mcp-macos@0.1.1","maintainers":[{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"}],"homepage":"https://github.com/dockndevai/mcp-macos#readme","bugs":{"url":"https://github.com/dockndevai/mcp-macos/issues"},"os":["darwin"],"bin":{"mcp-macos":"dist/index.js"},"dist":{"shasum":"eb496dbef0f78a3b34ab3a890ce6cfd04e038fb4","tarball":"https://registry.npmjs.org/@dockndevai/mcp-macos/-/mcp-macos-0.1.1.tgz","fileCount":36,"integrity":"sha512-gOFymTMIBlkgmu5trw7MxZlTRccyC8DwulntxAQZSM3xJS5LjBnSD0jhqC/5XTz1RaqSGvQnid/wHfmWIrOwKw==","signatures":[{"sig":"MEYCIQD3wXUwhECjcwSZspQEmKJkWtiTuLrE4gq+N8rqOa0sxAIhAOzMEBXOPdZS8RndEfnGkS8GoHnqLlgDfuHmLpGXYaZp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dockndevai%2fmcp-macos@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":106104},"type":"module","engines":{"node":">=22"},"gitHead":"c1f3188e5997db392c3e7fe5bbfa7c38e7a79f54","mcpName":"io.github.dockndevai/mcp-macos","scripts":{"dev":"tsx watch src/index.ts","lint":"tsc -p tsconfig.json --noEmit","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"},"repository":{"url":"git+https://github.com/dockndevai/mcp-macos.git","type":"git"},"_npmVersion":"10.9.8","description":"Model Context Protocol server for macOS — observe and operate a Mac (files, processes, apps, screenshots, shell, AppleScript, GUI) with safe-by-default access controls.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.5.4","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.13","vitest":"^5.0.0","typescript":"^7.0.2","@types/node":"^26.5.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-macos_0.1.1_1789235867636_0.7203425167672501","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"os":["darwin"],"_id":"@dockndevai/mcp-macos@0.2.0","bin":{"mcp-macos":"dist/index.js"},"bugs":{"url":"https://github.com/dockndevai/mcp-macos/issues"},"dist":{"shasum":"5adf2bc067820d47122cd49d4572fcf17ac80e6d","tarball":"https://registry.npmjs.org/@dockndevai/mcp-macos/-/mcp-macos-0.2.0.tgz","fileCount":39,"integrity":"sha512-BYYGSwnN6lBaqYAhLvJRcmS2hgstDmXZogjBoEpr43IWjR9Jich1JgyucevXd1OrC36g0qdFqn3M84LdZZ1hwA==","signatures":[{"sig":"MEYCIQDe9Pn77X/CKFgdG95yoOeRYufmyuovnL4qZLbzAjeaRgIhAKDhvtc+nMYTotYaUTutNSmw0kTC48+b/J+XnIMzdzEO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIECtCciePNtVSdRHXm6q2ksE8mBFRv8IkxjiYuiyUiK4AiAxdQKL2J0N0NYhqwn8VFbj1vc84SF1R7RoX072qZDiPw=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dockndevai%2fmcp-macos@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":116107},"name":"@dockndevai/mcp-macos","type":"module","engines":{"node":">=22"},"gitHead":"5a98acde6b3856b46024aaddc2708f9169e8e370","license":"MIT","mcpName":"io.github.dockndevai/mcp-macos","scripts":{"dev":"tsx watch src/index.ts","lint":"tsc -p tsconfig.json --noEmit","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/index.js","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"version":"0.2.0","_npmUser":{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"},"homepage":"https://github.com/dockndevai/mcp-macos#readme","keywords":["mcp","model-context-protocol","macos","mac","automation","applescript","computer-use","llm","ai"],"repository":{"url":"git+https://github.com/dockndevai/mcp-macos.git","type":"git"},"_npmVersion":"10.9.8","description":"Model Context Protocol server for macOS — observe and operate a Mac (files, processes, apps, screenshots, shell, AppleScript, GUI) with safe-by-default access controls.","directories":{},"maintainers":[{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"}],"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.5.4","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.13","vitest":"^5.0.0","typescript":"^7.0.2","@types/node":"^26.5.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-macos_0.2.0_1790685035654_0.6586207967974238"}}},"time":{"created":"2026-09-10T16:07:23.683Z","modified":"2026-09-29T12:30:36.070Z","0.1.0":"2026-09-10T16:07:24.409Z","0.1.1":"2026-09-12T17:57:47.759Z","0.2.0":"2026-09-29T12:30:35.743Z"},"bugs":{"url":"https://github.com/dockndevai/mcp-macos/issues"},"license":"MIT","homepage":"https://github.com/dockndevai/mcp-macos#readme","keywords":["mcp","model-context-protocol","macos","mac","automation","applescript","computer-use","llm","ai"],"repository":{"url":"git+https://github.com/dockndevai/mcp-macos.git","type":"git"},"description":"Model Context Protocol server for macOS — observe and operate a Mac (files, processes, apps, screenshots, shell, AppleScript, GUI) with safe-by-default access controls.","maintainers":[{"name":"dock-n-dev-ai","email":"ankitcs17071993@gmail.com"}],"readme":"# mcp-macos\n\n[![npm](https://img.shields.io/npm/v/@dockndevai/mcp-macos)](https://www.npmjs.com/package/@dockndevai/mcp-macos)\n[![CI](https://github.com/dockndevai/mcp-macos/actions/workflows/ci.yml/badge.svg)](https://github.com/dockndevai/mcp-macos/actions/workflows/ci.yml)\n[![licence](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)\n\nA **safe-by-default** [Model Context Protocol](https://modelcontextprotocol.io) 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).\n\nIt 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](https://dockndevai.github.io/) — one governance model across all of them.\n\n> Pure Node + `osascript`/`screencapture` — no native add-ons. macOS only.\n\n## What it gives an agent\n\nThe server starts **read-only** (see [Safe by default](#safe-by-default)); higher-capability tools are only registered when you raise the mode.\n\n| Tool | For | Needs mode |\n|---|---|---|\n| `system_info` | macOS version, hardware, memory, load, uptime | read-only |\n| `list_directory` / `read_file` | browse & read files (path-allowlisted) | read-only |\n| `list_processes` | running processes by CPU/mem | read-only |\n| `get_clipboard` | read the clipboard | read-only |\n| `list_apps` / `get_frontmost_app` | running apps; the active one | read-only |\n| `screenshot` | capture the screen as a PNG | read-only |\n| `write_file` | create/overwrite a file (confirms on overwrite) | read-write |\n| `set_clipboard` / `notify` / `open` | set clipboard, notify, open a file/URL/app | read-write |\n| `run_command` | run a program (argv, no shell) | admin + `MACOS_ALLOW_EXEC` |\n| `run_applescript` | run AppleScript / JXA | admin + `MACOS_ALLOW_EXEC` |\n| `kill_process` | signal a process | admin + `MACOS_ALLOW_EXEC` |\n| `delete_path` | move a path to the Trash | admin + `MACOS_ALLOW_DELETE` |\n| `type_text` / `key_press` / `click` / `move_mouse` | drive the GUI | admin + `MACOS_ALLOW_INPUT` |\n\n## Install\n\n```bash\nnpx -y @dockndevai/mcp-macos\n```\n\nRequires **macOS** and **Node ≥ 22**. `click`/`move_mouse` also need [`cliclick`](https://github.com/BlueM/cliclick) (`brew install cliclick`).\n\n## Configure\n\n```json\n{\n  \"mcpServers\": {\n    \"macos\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dockndevai/mcp-macos\"],\n      \"env\": {\n        \"MACOS_MODE\": \"read-only\"\n      }\n    }\n  }\n}\n```\n\nSee [docs/CLIENTS.md](docs/CLIENTS.md) for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and [.env.example](.env.example) for every supported variable.\n\n## Safe by default\n\nThis server can drive an entire Mac, so the access model (enforced by [`src/security.ts`](src/security.ts)) is deliberately strict — defence in depth, not documentation:\n\n| Question | Setting | Default | Notes |\n|---|---|---|---|\n| 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**. |\n| Which paths can it touch? | `MACOS_PATH_ALLOWLIST` | *(anywhere)* | Comma-separated roots. When set, any file op outside them is refused. |\n| 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. |\n| Can it run commands? | `MACOS_ALLOW_EXEC` | `false` | Gates `run_command`, `run_applescript`, `kill_process` (on top of admin). |\n| Restrict which programs? | `MACOS_COMMAND_ALLOWLIST` | *(any)* | When set, `run_command` may only invoke these program names. |\n| Can it delete? | `MACOS_ALLOW_DELETE` | `false` | Gates `delete_path` (moves to the **Trash**, recoverable). |\n| Can it drive the GUI? | `MACOS_ALLOW_INPUT` | `false` | Gates `type_text`/`key_press`/`click`/`move_mouse`. |\n| Preview without doing | `MACOS_DRY_RUN` | `false` | Mutating tools validate + log intent, then return. |\n| Audit trail | `MACOS_AUDIT_LOG` | `true` | JSON line to stderr per guarded operation (`ALLOW`/`DENY`/`DRY_RUN`). |\n| 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. |\n\nSee [SECURITY.md](SECURITY.md).\n\n## macOS permissions\n\nThe host process (your terminal / MCP client) must be granted, in **System Settings → Privacy & Security**:\n\n- **Screen Recording** — for `screenshot`.\n- **Accessibility** — for `type_text` / `key_press` / `click` / `move_mouse`.\n- **Automation** (per-app prompts) — for `run_applescript` and app control.\n- **Files and Folders / Full Disk Access** — to read/write outside the default sandbox.\n\nYou'll be prompted the first time each is needed; nothing works around a permission you haven't granted.\n\n## Developing\n\n```bash\nnpm install\nnpm run build\nMACOS_MODE=read-only node dist/index.js\n# introspect the tool list:\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/index.js\n```\n\n## Licence\n\nMIT\n","readmeFilename":"README.md"}