mac-control-mcp

mac-control-mcp

原生 Swift MCP 服务，可全面自动化 macOS。153 个工具打包在一个经过签名的 .app 应用中，无需 Python、Node 运行时或 Electron。完整工具列表及参数见：docs/TOOLS.md。

让任何兼容 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）都能：

• 读取和修改任何正在运行的应用的辅助功能树
• 操控 Safari 和 Chrome（标签页、导航、JS 执行）
• 捕获屏幕、显示器或特定窗口（ScreenCaptureKit）
• 对屏幕内容进行 OCR
• 点击、输入、滚动、拖动、发送按键事件
• 控制窗口（移动 / 调整大小 / 全屏 / 最小化 / 置前）
• 管理剪贴板
• 启动 / 激活 / 退出应用
• 搜索 Spotlight 索引（NSMetadataQuery）并启动搜索结果
• 切换深色模式、调节音量、列出显示器、检查菜单

安装

需要 macOS 14.0 或更高版本。提供四种方式，按简便程度排序：

1. 一键安装（推荐用于 Claude Desktop）

此服务以 MCP Bundle 形式发布，这是一个包含 manifest.json 的 zip 文件，Claude Desktop 可直接读取：

1. 从最新发布版本下载 mac-control-mcp-v<version>.mcpb。
2. 双击 .mcpb 文件。Claude Desktop 将打开安装对话框。
3. 点击 Install。服务将以 mac-control-mcp 名称注册，并立即在新聊天中可用。
4. 首次调用工具时，macOS 会请求 TCC 授权（屏幕录制、辅助功能、Apple Events）。只需授予这三项权限一次——该应用包经过 Developer-ID 签名和公证，因此更新后授权仍然有效。

它也已列入官方 MCP Registry，名称为 io.github.AdelElo13/mac-control-mcp，因此任何支持该注册表的 MCP 客户端都可以通过搜索“mac-control”找到它。

2. 通过 npm / npx 安装

适用于配置方式为命令行而非文件路径的客户端。npm 包 mac-control-mcp 是一个轻量启动器：它没有运行时依赖项，安装时会从本仓库的 GitHub 发布页下载对应版本经过公证的 MacControlMCP.app，并根据发布的 .sha256 文件验证其完整性，拒绝任何逃逸出安装目录的归档条目，还会通过 codesign --verify --deep --strict、spctl --assess --type execute 和固定的 Team ID（A3W973JZ49）重新验证应用包。因此首次运行会下载约 3 MB 的文件，之后则在本地运行。

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mac-control-mcp": {
      "command": "npx",
      "args": ["-y", "mac-control-mcp"]
    }
  }
}

Claude Code：

claude mcp add mac-control-mcp -- npx -y mac-control-mcp

Cursor — ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mac-control-mcp": {
      "command": "npx",
      "args": ["-y", "mac-control-mcp"]
    }
  }
}

ChatGPT（开发者模式，本地 MCP 连接器）— mcp.json：

{
  "mcpServers": {
    "mac-control-mcp": {
      "command": "npx",
      "args": ["-y", "mac-control-mcp"],
      "transport": "stdio"
    }
  }
}

启动器会自行处理两个标志，不会将它们传递给二进制文件：

npx -y mac-control-mcp --version    # version of the bundled .app
npx -y mac-control-mcp --app-path   # path to MacControlMCP.app

手动授予 macOS 权限时需要使用 --app-path。请注意，TCC 授权会授予启动此进程的 MCP 宿主应用（Claude Desktop、Cursor、你的终端），而不是 npx 或脚本；从客户端运行一次 permissions_status 工具，即可查看缺少哪些授权，以及这些授权应授予哪个应用。

MAC_CONTROL_MCP_SKIP_DOWNLOAD=1 会跳过下载（适用于 CI、沙盒构建）；HTTPS_PROXY 和 NO_PROXY 也会得到支持。

3. 下载预构建应用

如果你不使用 Claude Desktop，或希望手动控制：

1. 从最新发布页下载 MacControlMCP-v<version>-macos-universal.tar.gz。
2. 解压并将 MacControlMCP.app 移动到 ~/Applications/。
3. 将 MCP 客户端指向以下二进制文件：

{
  "mcpServers": {
    "mac-control-mcp": {
      "type": "stdio",
      "command": "/Users/you/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP"
    }
  }
}

将该代码块添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（Claude Desktop）或 ~/.claude.json → mcpServers（Claude Code）。

使用发布的 SHA-256 校验下载文件：

shasum -a 256 MacControlMCP-v<version>-macos-universal.tar.gz
# should match MacControlMCP-v<version>-macos-universal.sha256 on the release

4. 从源代码构建

适用于贡献者，或希望调整代码的用户。需要 Swift 6 / Xcode 16+：

git clone https://github.com/AdelElo13/mac-control-mcp.git
cd mac-control-mcp
./scripts/build-bundle.sh

生成的文件为 ~/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP。如果钥匙串中没有 Developer ID 证书，则会回退到临时签名（可在本地使用，但每次重新构建后 TCC 授权都会重置）。

要重新签名并重新公证现有的 Apple Developer 账户：

# one-time: store notary credentials in keychain
xcrun notarytool store-credentials "mac-control-mcp" \
    --apple-id "[email protected]" --team-id "XXXXXXXXXX"

# subsequent builds:
NOTARIZE_PROFILE=mac-control-mcp ./scripts/build-bundle.sh

工具概览

所选类别——此表为精选子集，并非完整列表。 完整的自动生成工具参考（包含每个工具、其说明以及必需／可选参数，直接从工具注册表重新生成，因此内容不会偏离），请参阅 docs/TOOLS.md。

类别	工具
权限	permissions_status, request_permissions
辅助功能	find_element(s), query_elements, list_elements, get_ui_tree, ax_tree_augmented, get_element_attributes, set_element_attribute, read_value, perform_element_action, wait_for_element, scroll_to_element
应用生命周期	list_apps, launch_app, activate_app, quit_app, force_quit_app, wait_for_app, focused_app
窗口	list_windows, focus_window, move_window, resize_window, set_window_state, wait_for_window, move_window_to_display
输入	click, mouse_event, drag_and_drop, scroll, type_text, press_key, press_key_sequence, key_down, key_up, convert_coordinates
菜单	click_menu_path, list_menu_paths, list_menu_titles
浏览器	browser_list_tabs, browser_get_active_tab, browser_navigate, browser_new_tab, browser_close_tab, browser_eval_js, browser_dom_tree, browser_visible_text, browser_iframes
屏幕	capture_screen, capture_screen_v2, capture_window, capture_display, ocr_screen
剪贴板	clipboard_read, clipboard_write, clipboard_clear
Spotlight	spotlight_search, spotlight_open_result
系统	set_volume, set_dark_mode, list_displays
文件对话框	file_dialog_set_path, file_dialog_select_item, file_dialog_confirm, file_dialog_cancel, wait_for_file_dialog
Apple 应用	mail_send, imessage_send, imessage_list_recent, calendar_create_event, calendar_list_events, reminders_create, reminders_list, contacts_search
语音与录制	speech_to_text, text_to_speech, audio_record, record_screen
撤销	undo_last_action, undo_peek

共 153 个工具——完整的生成列表请参阅 docs/TOOLS.md。

何时使用哪个工具

多个工具的用途有所重叠。根据它们的实际实现：

屏幕捕获——capture_screen 与 capture_screen_v2 与 capture_window 与 capture_display

• capture_screen——将主显示器（或其中的矩形区域）捕获为 PNG 文件，并返回文件路径及宽度／高度。简单、同步，不应用大小限制。
• capture_screen_v2——仅捕获主显示器，但会将 PNG 保存为内容寻址资源，路径为 ~/.mac-control-mcp/artifacts/<sha256>.png，并返回 {content_ref, bytes, sha256}。默认设置为 inline=false，并将图像缩小到 max_dimension／max_bytes 限定的大小（默认为 4000px／4MB），专门用于避免超大内联图像撑满 MCP 客户端的上下文窗口（其描述中将此作为修复 claude-code issues #13383/#45785 的方案）。如果图像会经过大模型上下文，而不是直接保存到磁盘，优先使用此工具。
• capture_window——按 PID 截取一个特定窗口的屏幕截图（可选按 title_contains 筛选），而不是整个显示器。
• capture_display——按 list_displays 返回的索引截取一个特定物理显示器的屏幕截图，适用于多显示器设置。

无障碍树／元素查找——find_element 与 find_elements 与 query_elements 与 list_elements 与 get_ui_tree 与 ax_tree_augmented

• list_elements——列出某个 PID 对应的可操作元素（以扁平、实用的方式展示“我能点什么”）。
• find_element——返回某个 PID 中第一个符合角色／标题筛选条件的元素。
• find_elements——匹配方式与 find_element 相同，但会返回所有匹配项，而不只是第一个。
• query_elements——按角色／标题／值进行正则搜索（正则无效时回退为不区分大小写的子字符串搜索）；当简单的角色／标题筛选不够精确时使用。
• get_ui_tree——遍历进程的完整无障碍树（包括容器），并为后续调用分配稳定的元素 ID。它比 list_elements／find_element(s) 更耗资源，但只有它能提供结构／层级信息。
• ax_tree_augmented——与 get_ui_tree 类似，但会执行一次 OCR，并将 OCR 识别出的标签按几何位置关联到没有原生标签的 AX 节点。专用于原生 AX 树稀疏且缺少标签的 Electron／Chromium／Canvas 应用；此工具开销较大（需要执行一次 OCR），因此先使用 get_ui_tree，节点返回时没有标签再回退使用此工具。

安全模型

• 会写入文件的工具（capture_*、ocr_screen）会通过严格的允许列表校验 output_path——仅接受用户专属临时目录（NSTemporaryDirectory()）以及 ~/Desktop、~/Documents、~/Downloads、~/Pictures。为防止路径重定向，会拒绝目标路径中的符号链接。特意排除 /tmp，因为该目录由多个用户共享，会引入 TOCTOU 窗口。
• browser_eval_js 中的 AppleScript 字符串插值会通过 JSON.stringify 将用户代码封装在 (0, eval)(…) 中，因此引号／换行符／Unicode 字符无法跳出封装。
• 不会发起网络调用。所有操作都是本地系统集成。
• 代码会限制对密码字段的访问，而非依赖指令。角色或子角色为 AXSecureTextField 的字段绝不会返回其值或长度，所有写入方式都会被拒绝，并返回 reason: secure_field：元素写入、text_* 编辑、act、未指定目标的 type_text，以及当此类字段处于焦点时通过 press_key、press_key_sequence 和 key_down 输入文本按键或 Cmd+V。当此类字段处于焦点时，也无法按下菜单栏和上下文菜单中的项目（“粘贴”“开始听写”“表情与符号”）；弹出菜单和组合框选项菜单仍可使用。导航键（Tab、Return、Escape、方向键）仍可正常使用，因此 Agent 可以将字段交由用户操作。此保护不适用于运行任意页面 JavaScript 的 browser_eval_js。

状态（已在当前版本中验证）

范围	状态
单元测试／集成测试套件	swift test，本地和 CI（macos-15）上均全部通过——参见 ci.yml
实时工具探测	通过真实 MCP stdio 对运行中的二进制文件进行端到端测试的工具子集，全部通过
破坏性工具（volume、dark mode、force_quit_app、drag_and_drop、file_dialog_*）	已通过可逆方式进行实时验证
代码签名	Developer ID Application (A3W973JZ49)，启用了强化运行时
Apple 公证	已通过 Apple Notary Service 验收，票据已装订，spctl 报告 source=Notarized Developer ID
Gatekeeper 流程	在设置了 com.apple.quarantine 扩展属性的情况下解压并启动；无需右键选择“打开”
MCP Registry	已发布为 io.github.AdelElo13/mac-control-mcp（当前版本见 server.json）——以 .mcpb 捆绑包形式分发，可一键安装
架构	通用二进制文件（arm64 + x86_64）。Intel 切片可顺利编译，但尚未在实际 Intel 硬件上进行运行时验证
move_window_to_display	已跳过——需要至少 2 台显示器

如果你遇到未经测试的情况，请提交附带复现步骤的问题报告——我们很乐意尽快修复。

注意事项

• 跨源 iframe 会阻止 browser_eval_js——这是同源策略导致的，并非工具本身的限制。要操作来自其他源的嵌入式 iframe 内容，请使用 AX 坐标或合成 CGEvents。
• 首次运行时的 TCC 提示无法避免。 macOS 要求用户首次使用时授予屏幕录制、辅助功能和 Apple Events 权限。Info.plist 中的用途说明字符串会让授权对话框清楚显示原因，但你仍需在“系统设置”中点击一次“允许”。

开发

# Run the test suite
swift test

# Build without packaging
swift build -c release

# Live probe the running binary via MCP stdio
python3 scripts/mcp-sweep.py  # if included

许可证

MIT——参见 LICENSE。

贡献

欢迎提交问题报告和拉取请求。尤其欢迎对抗性审查——此前的版本在发布前经过了 11 轮外部审查。