How do I use mcp-macos?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-macos show me the top 5 processes by CPU usage" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-macos

Q: Which integrations are available for this server?

Allows an agent to observe and operate a macOS system: read files, list processes and apps, take screenshots, write files, set the clipboard, post notifications, open items, and with admin opt-ins run commands/AppleScript, delete to Trash, kill processes, and drive the GUI.

by dockndevai

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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`

Related MCP server: Open Computer Use

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

Licence

MIT

Available Tools

8 tools

get_clipboardRead the clipboardA

Read-onlyIdempotent

Return the current text contents of the macOS clipboard.

Inputs: no named parameters.

get_frontmost_appFrontmost appA

Read-onlyIdempotent

Return the name of the frontmost (active) application.

Inputs: no named parameters.

list_appsList running appsA

Read-onlyIdempotent

List the names of currently running (non-background) applications.

Inputs: no named parameters.

list_directoryList a directoryA

Read-onlyIdempotent

List the entries (name, type, size) of a directory. Honours the path allowlist.

Inputs: path (required).

list_processesList processesA

Read-onlyIdempotent

List running processes (pid, cpu%, mem%, command), busiest first.

Inputs: limit, filter.

read_fileRead a fileA

Read-onlyIdempotent

Read a text file's contents (capped at MACOS_MAX_FILE_BYTES). Honours the path allowlist.

Inputs: path (required).

screenshotScreenshotA

Read-onlyIdempotent

Capture the screen and return it as a PNG image. Needs Screen Recording permission for the host process.

Inputs: no named parameters.

system_infoSystem infoA

Read-onlyIdempotent

Report macOS version, hardware, memory, load, uptime and the current user.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-09-10 17:46 across 8 tools

Disambiguation5/5

Every tool has a clearly distinct purpose: system summary, directory listing, file reading, process listing, clipboard access, app listing, active app lookup, and screen capture. Even related tools like list_apps and get_frontmost_app are cleanly separated by scope.

Naming Consistency4/5

Most tools follow a clear list_* or get_* verb pattern, with read_file as another verb_noun. system_info and screenshot break the pattern, but the naming remains readable and mostly predictable.

Tool Count5/5

Eight tools is well-scoped for a macOS observation/utility server. Each tool covers a distinct capability and none feel redundant or excessive.

Completeness4/5

The server covers common macOS inspection needs: system status, file browsing, process listing, clipboard, apps, and screen capture. It is intentionally read-only, so missing write operations are not glaring gaps, though a few extensions like file metadata or clipboard image support could be added.

Maintenance

ActivityActive

ResponsivenessOutdated data

Resources

Related MCP Connectors

SentinelX MCP
app.sentinelx
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shell Access OS Automation
216
https://mcp.sentinelx.app/mcp/mcp
PC Remote Commander
io.github.pcremotecommander
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
File Systems Command Line Browser Automation
11
https://pc-remote-commander.pcremotecommander.workers.dev/mcp
DNS-DATA RemoteDeprecated
com.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
File Systems Command Line OS Automation
11
https://mcp.dns-data.com/mcp
OakallowA
io.github.oakallow
Runtime permission, approval, and audit layer for AI agent tool execution.
Autonomous Agents Security
431
https://api.oakallow.io/mcp

Related MCP Servers

Automation MCP
OS Automation App Automation
ashwwwin
A
license
Not graded
quality
D
maintenance
Enables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.
Updated a year ago (2025-06-11 02:24 UTC)
10 npm
415
MIT
Open Computer Use
OS Automation App Automation Autonomous Agents
aibo204
A
license
Not graded
quality
B
maintenance
Enables AI agents to observe and control the user's live desktop by listing apps, reading accessibility trees, and performing clicks, typing, scrolling, dragging, and other input actions with per-action approvals and local audit archives.
Updated 2 months ago (2026-09-11 09:40 UTC)
1
MIT
chatuse
Autonomous Agents OS Automation
fazakis
A
license
Not graded
quality
B
maintenance
Enables AI assistants to inspect and control macOS apps via accessibility trees, screenshots, OCR, and input simulation, with a visible pointer.
Updated a month ago (2026-10-16 12:10 UTC)
MIT
UseMyMac
OS Automation Shell Access Command Line
yunfeng-enrich
A
license
Not graded
quality
B
maintenance
Securely control your Mac from AI assistants using native mouse, keyboard, screenshot, and shell tools.
Updated 2 months ago (2026-09-14 16:46 UTC)
34
3
MIT

mcp-macos

What it gives an agent

Install

Configure

Safe by default

macOS permissions

Developing

Licence

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Automation MCP

Open Computer Use

chatuse

UseMyMac