🍏 macOS 电脑使用（MCP 服务器）

一个超快速的原生 模型上下文协议（MCP） 服务器，为 LLM 和自主代理提供 macOS 上的视觉检查与故障安全桌面自动化。

它基于编译的 Swift 核心构建，利用 Apple 原生 CoreGraphics、Vision OCR（VNRecognizeTextRequest） 和 Accessibility API 实现语义后台操作。非定向输入仍保留为显式的全局 CoreGraphics 回退。

⚡ 核心亮点

• 🎯 原生 Apple Vision OCR（find_text / click_text）：通过显式的 exact、word、prefix 或 substring 匹配查找可见文本，除非指定了出现次数，否则拒绝模糊点击。

• 🛡️ 故障安全定位：windowId 具有权威性。无效 ID 以及应用/窗口不匹配会返回错误，而不是回退到其他窗口或整个显示器。

• 🔐 默认安全：除非 MCP 进程以 MACOS_COMPUTER_USE_UNSAFE=1 启动，否则全局指针/键盘输入、前台应用激活和自定义 AppleScript 均被禁用。

• 🩺 权限预检：get_capabilities 报告辅助功能、屏幕录制和事件合成就绪状态，而不会调用 macOS 权限请求 API。

• ♿ 后台辅助功能操作：检查控件、设置值、执行语义操作，以及定位可编辑控件，而无需激活其应用程序。

• ⏱️ 语义后台等待：等待辅助功能控件出现，无需截图或屏幕录制权限。

• 🖱️ 实时代理光标：点击和滚动会将一个独特的、可点击穿透的光标覆盖层滑动到目标位置，显示成功或失败反馈，并在空闲时淡出，而不会移动您的物理指针。

• 👁️ 匹配截图光标（mark_cursor）：返回的操作截图会在目标坐标处渲染相同的代理光标。

• ⚡ 响应式 UI 同步（wait_for_text）：用高速 OCR 轮询循环取代盲目的 sleep() 超时，在动态自动补全下拉菜单、模态框或状态变化出现时立即解析。

• 🖼️ 窗口隔离屏幕捕获：在后台干净地捕获目标应用程序缓冲区（screencapture -l <wid> -o -x），而不会将窗口带到前台或捕获重叠窗口。

Related MCP server: ScreenHand

🛠️ 暴露的工具

🚀 安装与设置

使用 npx 运行

配置 MCP 客户端以下载、构建并启动最新的公共包：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"]
    }
  }
}

该包包含一个临时签名的通用 Swift 辅助程序，适用于 Apple Silicon 和 Intel Mac，因此 npx 不需要本地 Swift 编译器或安装脚本批准。

默认配置暴露语义后台自动化和只读检查。对于有意需要全局指针/键盘输入、前台激活或任意 AppleScript 的工作流，请显式选择加入：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"],
      "env": {
        "MACOS_COMPUTER_USE_UNSAFE": "1"
      }
    }
  }
}

1. 先决条件

• macOS 13.0+（Apple Silicon 或 Intel）

• Node.js 20+

• Xcode 命令行工具（仅从源代码构建时需要）：

  xcode-select --install

2. 克隆与构建

git clone https://github.com/johnexzy/macos-computer-use.git
cd macos-computer-use
npm install
npm run build

🔒 基于能力的 macOS 权限

仅授予您使用的工具所需的权限。macOS 将权限归属于运行 MCP 服务器的主机应用程序（Terminal、OpenCode、Cursor、VS Code 等）：

1. 辅助功能：语义检查和操作所需。它不需要屏幕录制权限。

2. 屏幕与系统音频录制：仅截图和 Vision OCR 工具（如 screenshot、find_text、click_text 和 wait_for_text）需要。

3. 事件合成：不安全模式下的全局 CoreGraphics 点击、输入、按键和滚动需要事件发布访问权限。语义辅助功能操作不使用此全局回退。

4. 自动化：仅当启用不安全模式且 run_applescript 向另一个应用程序发送事件时，macOS 才可能请求。核心输入和后台工具使用原生辅助程序，而不是 System Events。

在受保护操作之前调用 get_capabilities。权限检查使用 Apple 的预检 API，不会打开权限提示。如果访问权限缺失，截图/OCR 和全局输入路径会在分派前返回 SCREEN_RECORDING_PERMISSION_REQUIRED 或 INPUT_POSTING_PERMISSION_REQUIRED。在系统设置中手动授予访问权限，然后如果主机仍持有过时的隐私状态，请重新连接 MCP。

macOS 可能仍要求主机应用在授予新隐私权限后重新启动。这是 macOS 强制执行的；服务器不会反复提示或请求无关权限。

后台 UI 自动化是协作性的：macOS 可以处理另一个进程中的辅助功能元素，但应用程序可能会忽略定向键盘事件或在后续版本中更改其标识符。这些工具在这些情况下会返回显式的“不支持/未确认”错误，而不是激活应用或报告虚假成功。

🔌 MCP 配置

将此服务器添加到您的 MCP 客户端配置中：

Antigravity / Claude Desktop / Cursor / Windsurf

添加到您的 mcp_config.json / claude_desktop_config.json：

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/macos-computer-use/server.mjs"]
    }
  }
}

🧪 直接测试原生 Swift 辅助程序

您可以直接从终端测试原生二进制文件：

# Display resolution and scaling
./native_helper size

# List active Chrome windows in Z-order
./native_helper list_windows "Google Chrome"

# Find a button or text on screen with Apple Vision OCR in ~30ms
./native_helper find_text "Search" "Google Chrome"

# Reactively wait for dynamic text to appear
./native_helper wait_for_text "quantum" "Google Chrome" nil 5.0

运行自动化的故障安全和匹配回归测试：

npm test

验证对后台计算器窗口的语义检查：

npm run test:background -- Calculator

打开计算器和系统设置后，运行实时原生应用冒烟套件。该测试选择加入不安全模式，因为它使用 AppleScript 创建和清理 TextEdit 夹具：

npm run test:live

变更工具结果包含一个 execution 对象，其中包含版本化契约、交付方法、验证级别、前台保留状态和目标。基于坐标的操作保留 status: "delivered_unverified"；使用语义检查、OCR 或截图验证重要的后续状态。

MCP 服务器在第一次点击或滚动时惰性启动一个光标覆盖层进程，并在 MCP 连接关闭时停止它。覆盖层从不拦截鼠标输入，加入所有 Spaces 和全屏窗口，如果 AppKit 无法显示它，则报告 cursorOverlay.status: "unavailable"，而不会阻止请求的操作。

📦 发布

推送到 main 会运行 npm 发布工作流。要发布新版本，请在合并前更新 package.json 和 package-lock.json 中的版本。已存在于 npm 上的版本会被测试并跳过。

📄 许可证

MIT © John Oba