MCP Mac Control

MCPM控制

    

把你的AI眼睛和手放在你的Mac上。

MCPMacControl是一种 MCP服务器 这将任何AI助手变成 代理计算机用户 --它可以看到你的屏幕，移动鼠标，在键盘上键入，并在屏幕上运行shell命令 任何macOS应用程序不仅仅是浏览器。

适用于Claude Code、Cursor、Windsurf和任何兼容MCP的客户端。

没有脚本。没有AppleScript。只需用简单的语言告诉AI你想要什么，然后看着它驱动你的Mac。

你的AI能用它做什么？

• 像QA工程师一样测试你的应用程序 --点击流程、填写表单、验证视觉状态
• 自动化遗留软件 没有API-导航菜单，从任何窗口提取数据
• 调试UI问题 通过查看屏幕截图并逐步重现问题
• 驱动原生应用 --Xcode、Figma、Finder、Mail、Excel——任何有窗口的东西
• 运行交互式终端会话 --支持TUI的完整PTY（vim、htop、docker日志）

*截取Safari的屏幕截图，单击搜索栏，然后键入anthropic.com* 这是一个真正的提示。AI会做剩下的事情。

安装

下载（推荐）

下载 MCPMacControl.app.zip 从 最新版本，解压缩，然后移动到 /Applications/.

发布版本使用Apple Developer ID证书进行签名和公证，因此macOS权限在更新过程中保持不变，不会出现网守警告。

从源代码构建

git clone https://github.com/sstraus/mcpmaccontrol
cd mcpmaccontrol
make build
make install

配置您的MCP客户端

添加到MCP客户端的配置中（例如。 ~/.claude.json 克劳德代码）：

{
  "mcpServers": {
    "mac-control": {
      "command": "/Applications/MCPMacControl.app/Contents/MacOS/mcpmaccontrol"
    }
  }
}

然后问你的AI： *“截取Safari的屏幕截图，然后单击搜索框”*

为什么不采用Playwright/浏览器自动化？

浏览器自动化工具仅控制浏览器。MCPMacControl控制 Mac上的所有内容 --本地应用程序、Electron应用程序、系统对话框、菜单栏、Dock。如果屏幕上有像素，克劳德可以看到它并与之交互。

它还包括完整的PTY shell会话，因此Claude可以运行 vim, docker, ssh，或任何交互式终端工具——而不仅仅是无头命令。

为什么A .app 捆绑？

与大多数MCP服务器不同，MCPMacControl需要macOS屏幕录制和辅助功能权限。macOS为每个应用程序而不是二进制文件授予这些权限。当从终端运行纯二进制文件时，macOS会将权限归因于 终端应用程序 （iTerm，Terminal.app），而不是二进制文件本身。这意味着：

• 重新生成二进制文件时，权限不会持久
• 每个启动二进制文件的终端应用程序都需要单独的权限授予
• 用户无法在系统设置中管理二进制文件的权限

将二进制文件包装在签名的 .app bundle在macOS隐私设置中赋予了它自己的身份。二进制文件仍然像任何MCP服务器一样通过stdio进行通信 .app bundle就是macOS识别它以进行权限管理的方式。

这就是为什么命令路径是 /Applications/MCPMacControl.app/Contents/MacOS/mcpmaccontrol 而不是 /usr/local/bin/mcpmaccontrol.

权限

首次启动时，macOS将提示输入两个权限：

授予两者 系统设置>隐私和安全。应用程序会自动注册。

特性

• 视觉反馈 --菜单栏图标，显示当前操作的本地弹出窗口，自动化前声音+橙色边框闪烁
• 输入安全 --在发送按键之前验证目标应用程序是否已聚焦，防止输入到达错误的窗口
• 应用程序上下文继承 — focus 传播到批处理中的后续操作，因此您可以编写 app 一次
• 已签署 .app 捆 --macOS权限在更新过程中保持不变，没有网守警告
• 区域捕捉 --仅截图保存令牌所需的内容
• 自动退出 当AI客户端断开连接时

工具

内置帮助

AI呼叫 help() 学习API：

• help() → 概述和工作流程
• help("actions") → 所有动作类型 do()
• help("shell") → 壳牌/PTY文件
• help("examples") → 用法示例

运作原理

克劳德在一个“看-想-行动”循环中运作——就像人类使用电脑一样：

1. capture_window("Safari")         → Screenshot saved to temp file
2. [Claude reads the image]         → "I see a search bar at (400, 50)"
3. do([                             → Click, type, press Enter
     {type:"click", app:"Safari", x:400, y:50},
     {type:"type", text:"anthropic.com"},
     {type:"key", key:"enter"}
   ])
4. capture_window("Safari")         → Verify the result

截图中的像素坐标直接指向 do() 动作坐标——无需转换。

区域捕捉

捕获窗口的一部分以保存令牌：

capture_window("Safari", region_x: 0, region_y: 0, region_width: 400, region_height: 300)

单击坐标： click_x = region_x + x_in_image, click_y = region_y + y_in_image.

这 do 工具

按顺序执行一个或多个操作：

do({"actions": [
  {"type": "click", "app": "Safari", "x": 400, "y": 50},
  {"type": "type", "text": "anthropic.com"},
  {"type": "key", "key": "enter"}
]})

操作类型

例子

点击：

{"type": "click", "app": "Safari", "x": 100, "y": 50}
{"type": "click", "app": "Finder", "x": 200, "y": 100, "button": "right"}
{"type": "click", "app": "Finder", "x": 200, "y": 100, "double": true}

键盘：

{"type": "type", "text": "Hello World"}
{"type": "key", "key": "enter"}
{"type": "key", "key": "cmd+v"}
{"type": "key", "key": "cmd+shift+g"}
{"type": "key", "key": "v", "modifiers": ["cmd"]}

纸卷：

{"type": "scroll", "app": "Safari", "x": 400, "y": 300, "delta_y": -100}

窗口控制：

{"type": "focus", "app": "Safari"}
{"type": "minimize", "app": "Finder"}
{"type": "restore", "app": "Finder"}
{"type": "resize", "app": "Safari", "width": 1024, "height": 768}
{"type": "close", "app": "TextEdit"}

壳牌会议

使用完整的PTY和终端模拟运行交互式终端会话（支持vim、htop等TUI应用程序）：

1. shell(action: "spawn")                                          → Get session ID
2. shell(action: "send_input", session_id: "ID", input: "ls")     → Send text
3. shell(action: "send_input", session_id: "ID", special_key: "enter")
4. shell(action: "get_snapshot", session_id: "ID", format: "ansi") → Get screen
5. shell(action: "close", session_id: "ID")                        → Cleanup

无头模式

不带菜单栏运行（适用于CI/CD）：

{
  "mcpServers": {
    "mac-control": {
      "command": "/Applications/MCPMacControl.app/Contents/MacOS/mcpmaccontrol",
      "env": {
        "MCPMACCONTROL_HEADLESS": "1"
      }
    }
  }
}

图像优化

屏幕截图针对AI视觉进行了优化：

• WebP有损格式（默认质量25，可通过1-100进行调整 quality 参数；小字形/图标使用50+）
• 按窗口点尺寸缩放（坐标匹配点击）
• 使用 区域捕捉 进一步减小大小和令牌

发展

make build          # Build signed .app bundle
make test           # Run tests
make install        # Install to /Applications
make clean          # Remove build artifacts
make verify-sign    # Check code signature

要使用自己的Apple Developer证书签名，请执行以下操作：

SIGN_IDENTITY="Developer ID Application: YOUR NAME (TEAMID)" make build

需求

• macOS 12+
• 转到1.24+（用于建筑）

许可证

麻省理工学院