mcp-macos

Name: mcp-macos
Author: dockndevai

本地服务

github.com/dockndevai生产力03 天前更新

代码仓库

关于 mcp-macos

mcp-macos 是默认安全的 MCP 服务，可观察和操作 Mac，能力涵盖文件与应用检查、GUI 控制和命令执行。适合需要 Mac 功能并采用分级权限、显式启用高权限及高影响操作人工确认的 Agent。

主要功能

01检查文件、应用、进程和屏幕
02写入文件并管理剪贴板
03打开项目并发送通知
04限制命令、删除和 GUI 控制
05限制路径和允许的命令
06审计操作并请求批准

适用场景

01以只读模式检查 Mac 状态
02在许可范围内写入文件
03启用指定的管理操作
04要求批准高影响操作

MCP 相关

它向 MCP 客户端提供 Mac 观察和操作工具，并根据配置模式注册工具。高影响操作可通过 MCP elicitation 请求人工批准。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dockndevai-mcp-macos": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-macos"
      ],
      "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>"
      }
    }
  }
}

启动命令npx -y @dockndevai/mcp-macos

需要配置的环境变量

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

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

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

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

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

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@dockndevai/mcp-macos0.2.1stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

mcp-macos

一个默认安全的 Model Context Protocol 服务，让 Agent 能够观察和操作 Mac——读取文件、列出进程和应用、截取屏幕截图（只读）；写入文件、设置剪贴板、发布通知、打开内容（读写）；此外，在明确选择启用后，还能运行命令 / AppleScript、将内容移至废纸篓、终止进程并操控图形界面（管理员）。

它以只读模式启动。启用任何高影响权限都需要同时使用 admin 模式和对应的独立标志，而最危险的操作还需要人工逐次批准。它是 dockndevai MCP 服务套件的一部分——所有服务采用统一的治理模式。

纯 Node + osascript/screencapture——无需原生扩展。仅适用于 macOS。

它能为 Agent 提供什么

服务以只读模式启动（参见默认安全）；只有提高模式后，才会注册更高权限的工具。

工具	用途	所需模式
`system_info`	macOS 版本、硬件、内存、负载、运行时间	只读
`list_directory` / `read_file`	浏览和读取文件（路径需在允许列表中）	只读
`list_processes`	按 CPU / 内存列出运行中的进程	只读
`get_clipboard`	读取剪贴板	只读
`list_apps` / `get_frontmost_app`	查看运行中的应用及当前活动应用	只读
`screenshot`	将屏幕截取为 PNG	只读
`write_file`	创建或覆盖文件（覆盖前会确认）	读写
`set_clipboard` / `notify` / `open`	设置剪贴板、发送通知、打开文件/URL/应用	读写
`run_command`	运行程序（使用 argv，不通过 shell）	管理员 + `MACOS_ALLOW_EXEC`
`run_applescript`	运行 AppleScript / JXA	管理员 + `MACOS_ALLOW_EXEC`
`kill_process`	向进程发送信号	管理员 + `MACOS_ALLOW_EXEC`
`delete_path`	将路径移至废纸篓	管理员 + `MACOS_ALLOW_DELETE`
`type_text` / `key_press` / `click` / `move_mouse`	操控图形界面	管理员 + `MACOS_ALLOW_INPUT`

安装

npx -y @dockndevai/mcp-macos

需要 macOS 和 Node ≥ 22。click/move_mouse 还需要 cliclick（brew install cliclick）。

配置

{
  "mcpServers": {
    "macos": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-macos"],
      "env": {
        "MACOS_MODE": "read-only"
      }
    }
  }
}

Claude Code / Cursor / Codex / VS Code / Windsurf 的配置示例见 docs/CLIENTS.md，所有支持的变量见 .env.example。

默认安全

此服务可以控制整台 Mac，因此访问模型（由 src/security.ts 强制执行）有意设置得非常严格——采取纵深防御，而非仅依赖文档说明：

问题	设置项	默认值	说明
它究竟能做什么？	`MACOS_MODE`	`read-only`	`read-only` 仅观察；`read-write` 可写入文件／剪贴板／打开内容；`admin` 还可执行命令／删除／终止进程／控制 GUI。超出当前模式的工具永远不会注册。
它可以访问哪些路径？	`MACOS_PATH_ALLOWLIST`	（任意路径）	以逗号分隔的根路径。设置后，任何对列表之外路径的文件操作都会被拒绝。
哪些路径始终为只读？	`MACOS_PROTECTED_PATHS`	系统路径 + 敏感信息	`/System`、`/usr`、`/bin`、`/sbin`、`/private`、`/Library`、`~/.ssh`、`~/.aws`、`~/.gnupg`、`~/Library/Keychains`——可读取，绝不修改。
它可以运行命令吗？	`MACOS_ALLOW_EXEC`	`false`	控制 `run_command`、`run_applescript`、`kill_process`（此外还需启用 admin 模式）。
限制可运行的程序？	`MACOS_COMMAND_ALLOWLIST`	（任意程序）	设置后，`run_command` 只能调用这些程序名称。
它可以删除内容吗？	`MACOS_ALLOW_DELETE`	`false`	控制 `delete_path`（移至废纸篓，可恢复）。
它可以控制 GUI 吗？	`MACOS_ALLOW_INPUT`	`false`	控制 `type_text`／`key_press`／`click`／`move_mouse`。
仅预览，不执行	`MACOS_DRY_RUN`	`false`	修改类工具会验证并记录操作意图，然后返回。
审计记录	`MACOS_AUDIT_LOG`	`true`	每次受保护的操作都会向 stderr 输出一行 JSON（`ALLOW`／`DENY`／`DRY_RUN`）。
交互式确认	（自动）	—	`run_command`、`run_applescript`、`delete_path`、`kill_process` 以及覆盖文件前，都会通过 MCP elicitation 请求人工批准；不支持 elicitation 的客户端则回退为使用这些标志。

请参阅 SECURITY.md。

macOS 权限

必须在系统设置 → 隐私与安全性中向宿主进程（你的终端／MCP 客户端）授予以下权限：

屏幕录制——用于 screenshot。
辅助功能——用于 type_text／key_press／click／move_mouse。
自动化（逐个应用授权）——用于 run_applescript 和应用控制。
文件与文件夹／完全磁盘访问权限——用于读取／写入默认沙盒之外的内容。

首次需要时，系统会提示你授予权限；未授予的权限无法绕过。

开发

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