Skip to content
Back to search

computer-use-mcp

Local macOS MCP server with desktop controls and persistent background Chrome DevTools automation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/logex-linux--computer-use-mcp/badge.svg)](/listings/logex-linux--computer-use-mcp)

HTML

<a href="/listings/logex-linux--computer-use-mcp"><img src="/api/listings/logex-linux--computer-use-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 340 lines
  1. # computer-use-mcp
  2. 一个本地运行的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务,让 LLM Agent 真正操作 macOS 桌面:截屏、移动/点击鼠标、拖拽、滚动、输入文字、按快捷键、查看窗口、读写剪贴板、启动 App。
  3. - **stdio MCP 服务**:服务自身不监听端口;后台 Chrome 使用本机 localhost DevTools 端口,Chrome 页面可访问网络。
  4. - **极简依赖**:Python 标准库 + PyObjC(Quartz / AppKit),CDP WebSocket 客户端无需额外依赖。
  5. - **35 个工具**:包含 macOS 桌面与后台 Chrome 控制,观察类和操作类分离,支持只读模式。
  6. - **坐标可换算**:截图元数据直接给出「图片像素 → 屏幕坐标」的换算系数。
  7. ## 环境要求
  8. - macOS 12 或更高版本(在 macOS 14.5 / Apple M2 上验证)。
  9. - Python 3.10+,且能 `import Quartz, AppKit`。
  10. - python.org 安装的系统 Python 通常已自带 PyObjC;如果没有:
  11. ```bash
  12. python3 -m pip install pyobjc-framework-Cocoa pyobjc-framework-Quartz
  13. ```
  14. 先确认:
  15. ```bash
  16. python3 -c "import Quartz, AppKit; print('PyObjC ok')"
  17. ```
  18. ## 快速开始
  19. ```bash
  20. cd "<path-to-computer-use-mcp>"
  21. ./bin/computer-use-mcp --version # computer-use-mcp 0.1.0
  22. ./bin/computer-use-mcp --print-tools # 查看完整工具 JSON Schema
  23. # 端到端冒烟测试(观察类,不动鼠标)
  24. python3 scripts/smoke_test.py
  25. ```
  26. `bin/computer-use-mcp` 会自动寻找一个带 PyObjC 的 `python3`,因此**不需要 pip install** 就能运行。需要指定解释器时:
  27. ```bash
  28. COMPUTER_USE_MCP_PYTHON=/path/to/python3 ./bin/computer-use-mcp
  29. ```
  30. 也可以安装为命令(可选):
  31. ```bash
  32. python3 -m pip install -e .
  33. computer-use-mcp
  34. ```
  35. ## 接入 MCP 客户端
  36. 将示例中的 `<path-to-computer-use-mcp>` 替换为本地项目目录的绝对路径。
  37. ### StepCode(`~/.stepcode/config.toml`)
  38. ```toml
  39. [mcp_servers.computer-use]
  40. command = "<path-to-computer-use-mcp>/bin/computer-use-mcp"
  41. args = []
  42. enabled = true
  43. ```
  44. 只读模式:
  45. ```toml
  46. [mcp_servers.computer-use.env]
  47. COMPUTER_USE_MCP_READ_ONLY = "1"
  48. ```
  49. ### Claude Desktop / 其他 JSON 配置
  50. 见 [examples/claude-desktop-config.json](examples/claude-desktop-config.json):
  51. ```json
  52. {
  53. "mcpServers": {
  54. "computer-use": {
  55. "command": "<path-to-computer-use-mcp>/bin/computer-use-mcp",
  56. "args": []
  57. }
  58. }
  59. }
  60. ```
  61. 通用形式永远是:
  62. ```text
  63. command: /绝对路径/computer-use-mcp/bin/computer-use-mcp
  64. args: []
  65. transport: stdio
  66. ```
  67. ## 权限(必须)
  68. macOS 会按**启动这个 MCP 服务的宿主程序**授予权限,而不是按脚本路径。通常需要给 StepCode / Terminal / iTerm 授权,然后**重启宿主程序和 MCP 服务**。
  69. 1. **辅助功能(Accessibility)** — 合成鼠标 / 键盘事件。
  70. `系统设置 → 隐私与安全性 → 辅助功能`
  71. 2. **屏幕录制(Screen Recording)** — 截屏。
  72. `系统设置 → 隐私与安全性 → 屏幕录制`
  73. 授权后可在 Agent 中调用:
  74. ```json
  75. {"name": "get_permissions", "arguments": {}}
  76. ```
  77. 返回:
  78. ```json
  79. {
  80. "accessibility": true,
  81. "screen_recording": true,
  82. "screen_locked": false,
  83. "frontmost_app": {"name": "Safari", "bundle_id": "com.apple.Safari", "pid": 1234}
  84. }
  85. ```
  86. 如果为 `false`,可以调用 `open_permission_settings` 直接打开对应面板。
  87. > **锁屏注意**:`screen_locked: true` 时,截图看到的是锁屏界面,合成输入无法送达应用窗口。请先解锁 Mac;`get_screen_info` 和截图元数据会返回 `warning` 字段提醒调用方。为避免把按键送进登录密码框,锁屏状态下 `type_text` / `press_keys` / `key_down` / `key_up` 的全局注入会被拒绝;显式指定 `target_pid` 的直投仍可用。
  88. ## 坐标系统与截图
  89. - 所有坐标单位是 **screen points**(逻辑点,不是 Retina 像素)。
  90. - 原点在主显示器**左上角**,X 向右,Y 向下。
  91. - 多显示器时,主屏左侧 / 上方的屏幕坐标为负数。`get_screen_info` 会返回每块屏幕的 `bounds`。
  92. - 截图默认:
  93. - `resolution: "logical"` → 未触发 `max_dimension` 缩小时,1 个图片像素 = 1 个屏幕点;
  94. - `max_dimension: 1600` → 最长边超过 1600 时等比缩小;
  95. - `format: "png"`。
  96. - 截图返回的文本元数据包含:
  97. ```json
  98. {
  99. "image_width": 1600,
  100. "image_height": 1000,
  101. "region": {"x": 0, "y": 0, "width": 1440, "height": 900},
  102. "coordinate_mapping": {
  103. "points_per_image_pixel_x": 0.9,
  104. "points_per_image_pixel_y": 0.9
  105. }
  106. }
  107. ```
  108. 把模型在图片上估的像素坐标换算成工具坐标:
  109. ```text
  110. screen_x = region.x + image_x * points_per_image_pixel_x
  111. screen_y = region.y + image_y * points_per_image_pixel_y
  112. ```
  113. 需要原始 Retina 分辨率时传 `resolution: "native", max_dimension: 0`;只需要局部细节时传 `x / y / width / height` 区域截图,避免整屏缩小后看不清小字。
  114. ## 工具
  115. ### 观察
  116. | 工具 | 说明 |
  117. | --- | --- |
  118. | `get_screen_info` | 显示器、缩放、光标、虚拟桌面、权限、锁屏状态、前台 App。**建议先调用**。 |
  119. | `screenshot` | 全屏 / 区域 / 窗口截图。参数:`display, x, y, width, height, window_id, resolution, max_dimension, format, quality`。返回文本元数据 + 图片。 |
  120. | `list_windows` | 按前后顺序列出窗口:`window_id, app, title, pid, bounds`。 |
  121. | `get_cursor_position` | 当前光标坐标。 |
  122. | `get_permissions` | 辅助功能 / 屏幕录制 / 锁屏 / 前台 App。 |
  123. | `clipboard_read` | 读取剪贴板文本。 |
  124. | `wait` | 等待 `milliseconds` 毫秒,给动画 / 启动留时间。 |
  125. ### 鼠标
  126. | 工具 | 说明 |
  127. | --- | --- |
  128. | `move_mouse` | `x, y, duration_ms`;`duration_ms: 0` 瞬移。 |
  129. | `click` | `x?, y?, button(left/right/middle), clicks(1-5), interval_ms, modifiers`。支持 shift-click。 |
  130. | `mouse_down` / `mouse_up` | 按住 / 松开鼠标键,用于手动拖拽。 |
  131. | `drag` | `x1, y1, x2, y2, duration_ms, button, modifiers`。 |
  132. | `scroll` | `dy, dx?, x?, y?, modifiers`;`dy > 0` 向上滚动。 |
  133. ### 键盘
  134. | 工具 | 说明 |
  135. | --- | --- |
  136. | `type_text` | `text, method(unicode/keycode), interval_ms, target_pid?`。Unicode 支持中文、Emoji。 |
  137. | `press_keys` | `keys: "cmd+c"` 或 `["cmd+a", "delete"]`,`repeats, interval_ms, hold_ms, target_pid?`。 |
  138. | `key_down` / `key_up` | 单独按住 / 释放按键或修饰键。 |
  139. 支持 `cmd/command`、`shift`、`option/alt`、`control/ctrl`、`fn`,以及 `enter`、`esc`、`tab`、`space`、`backspace`、方向键、`f1`–`f20`、`pageup/pgdn/home/end` 等。
  140. ### 窗口、App、系统
  141. | 工具 | 说明 |
  142. | --- | --- |
  143. | `focus_window` | 激活窗口所属 App 并前置。若同 App 有多个窗口,之后再点击目标窗口。 |
  144. | `activate_app` | 将已运行的 App 置前;未运行则启动。 |
  145. | `open_app` | 按名称、路径或 bundle id 启动 App。 |
  146. | `open_url` | 仅允许 `http`、`https`、`mailto`。 |
  147. | `open_permission_settings` | 打开辅助功能 / 屏幕录制设置面板。 |
  148. ### 后台 Chrome(Chrome DevTools Protocol)
  149. 这组工具通过 Chrome DevTools Protocol 控制标签页,不激活窗口、不用 Spotlight、不移动桌面鼠标。`chrome_start` 会启动独立的无头 Chrome,使用单独的持久化用户目录 `~/Library/Application Support/computer-use-mcp/chrome`;可在 MCP 服务重启后继续连接。它不会复用日常 Chrome 配置或其登录状态。
  150. | 工具 | 说明 |
  151. | --- | --- |
  152. | `chrome_start` | 启动后台 Chrome,可传 `url`,默认 `about:blank`。 |
  153. | `chrome_status` | 检查后台实例状态。 |
  154. | `chrome_connect` | 连接已启用远程调试的本机 Chrome,参数为 `port`。 |
  155. | `chrome_tabs` / `chrome_open_tab` / `chrome_navigate` / `chrome_close_tab` | 列出、打开、导航、关闭标签页。 |
  156. | `chrome_read_page` / `chrome_screenshot` | 读取页面标题、URL、可见文本或后台截图。 |
  157. | `chrome_click` / `chrome_type_text` | 通过 CDP 鼠标事件点击可见元素,或聚焦输入框并写入文本。 |
  158. | `chrome_stop` | 关闭本工具启动的独立 Chrome;拒绝关闭外部连接的实例。 |
  159. 最短调用流程:
  160. ```text
  161. chrome_start({"url":"https://example.com"})
  162. chrome_tabs({})
  163. chrome_read_page({"tab_id":"上一步返回的 tab_id"})
  164. chrome_screenshot({"tab_id":"上一步返回的 tab_id"})
  165. ```
  166. 从 MCP 客户端调用 `chrome_start` 后,无需保持 Chrome 窗口在前台。若要接管一个额外启动并启用了调试的 Chrome,可在启动 Chrome 时传入 `--remote-debugging-port=9222 --user-data-dir=/独立的/用户目录`,再调用 `chrome_connect({"port":9222})`。为避免泄露浏览器会话,**不要**对日常个人资料目录开放调试端口。macOS 上 Chrome 136+ 仅对非默认用户目录开放远程调试。
  167. 仅允许 `http`、`https` 和 `about:blank` 页面地址;端口及 WebSocket 必须是 localhost。页面点击、表单输入、导航和关闭标签会实际改变网页状态。此实现不暴露任意 JavaScript 执行工具。
  168. ### 只读模式
  169. 两种开启方式:
  170. ```bash
  171. ./bin/computer-use-mcp --read-only
  172. COMPUTER_USE_MCP_READ_ONLY=1 ./bin/computer-use-mcp
  173. ```
  174. 只读模式下,桌面输入操作、启动 / 停止 Chrome、打开 / 导航 / 关闭标签、页面点击和输入会返回 `isError: true`;桌面截图、Chrome 状态 / 标签 / 页面读取仍然可用。
  175. ## 典型 Agent 工作流
  176. ```text
  177. 1. get_screen_info
  178. → 确认屏幕、权限、是否锁屏、前台 App
  179. 2. screenshot {"max_dimension": 1600}
  180. → 看截图,定位目标
  181. 3. click {"x": 742, "y": 318}
  182. 或 type_text {"text": "hello"}
  183. 或 press_keys {"keys": "cmd+s"}
  184. 4. screenshot {"x": 600, "y": 200, "width": 600, "height": 400}
  185. → 用局部截图确认结果
  186. ```
  187. 给模型的提示词示例:
  188. > 打开 Safari,搜索「Model Context Protocol」,把第一条结果的标题和链接告诉我。每步操作后截图确认。
  189. ## 安全设计
  190. - MCP 服务仅使用 **stdio**;本机 Chrome 另通过 loopback-only DevTools 端口通信,Chrome 页面本身可能访问外网。
  191. - 不提供 shell / 任意 JavaScript 执行工具。
  192. - 浏览器 URL 限制为 `http/https/about:blank` 并拒绝凭据;DevTools HTTP 不跟随重定向,WebSocket 地址与连接均限定在 localhost。
  193. - stderr 日志会**脱敏**:不记录输入的文本、URL、按键、App 名、`target_pid` 的具体值,只记录长度 / 类型。
  194. - 合成输入可以造成真实后果(删除、发送、购买)。默认建议在 Agent 侧对危险动作做人工确认;不确定时使用只读模式。
  195. - `clipboard_read` 可能读到密码等敏感内容,仅在需要时使用。
  196. ## 项目结构
  197. ```text
  198. computer-use-mcp/
  199. ├── bin/computer-use-mcp # 免安装启动器(自动找带 PyObjC 的 python3)
  200. ├── src/computer_use_mcp/
  201. │ ├── server.py # MCP stdio JSON-RPC
  202. │ ├── tools.py # 35 个工具的 JSON Schema 与分发
  203. │ ├── chrome.py # 隔离后台 Chrome + DevTools Protocol
  204. │ ├── macos.py # Quartz/AppKit 桌面控制
  205. │ └── keymap.py # macOS 虚拟键码与快捷键解析
  206. ├── tests/ # 标准库 unittest(无需 pytest)
  207. ├── scripts/smoke_test.py # 通过 stdio 启动真实服务做端到端测试
  208. ├── examples/ # 客户端 Demo + StepCode/Claude 配置
  209. ├── pyproject.toml
  210. └── README.md
  211. ```
  212. ## 测试
  213. ```bash
  214. # 单元测试(协议、键位、坐标、参数校验)
  215. PYTHONPATH=src python3 -m unittest discover -s tests -v
  216. # 端到端:握手、工具列表、权限、截屏、窗口截图、错误码、只读模式
  217. python3 scripts/smoke_test.py
  218. # 额外验证真实输入(会移动鼠标;可选向测试 App 注入文字)
  219. python3 scripts/smoke_test.py --input
  220. python3 scripts/smoke_test.py --input --target-pid 12345
  221. ```
  222. 一次实际运行结果:
  223. ```text
  224. 58 tests OK
  225. PASS: computer-use-mcp is working
  226. display: 1440.0x900.0 points, scale 2.0
  227. permissions: accessibility=True screen_recording=True screen_locked=False
  228. ```
  229. 额外验证:
  230. - 用官方 Python MCP SDK `1.30.0` 的 `ClientSession` 通过 stdio 完成 `initialize` / `tools/list` / `tools/call`,并正确解析了返回的 `ImageContent`。
  231. - 对一个本地测试 Cocoa App:验证了单击、双击(本地事件监视器收到 1 次/2 次 mouseDown)、Unicode 文本注入(含中文),以及 `shift+left` 这类带修饰键的按键(`ABC` → 选中 `C` → 输入 `Z` 得到 `ABZ`)。
  232. - 锁屏时 `get_screen_info` / 截图会返回 `warning`,全局键盘输入会被拒绝,避免把按键送进登录密码框。
  233. ## 已知限制
  234. - **仅 macOS**;依赖 Quartz / AppKit。
  235. - **锁屏时**输入不会到达普通应用窗口;请先解锁。
  236. - 密码框等 **secure input** 会刻意忽略合成键盘事件。
  237. - `focus_window` 只能激活 App;同一 App 的多个窗口需要通过点击来精确前置(未使用 AXRaise)。
  238. - 受保护窗口(如部分系统窗口、DRM 内容)可能无法截图。
  239. - 某些游戏 / 远程桌面 / 虚拟机使用底层输入抓取,可能忽略合成事件。
  240. - 不包含 OCR;识别截图内容由调用方模型完成。
  241. - 多用户 / 远程桌面场景未专门验证。
  242. ## 故障排查
  243. | 现象 | 处理 |
  244. | --- | --- |
  245. | `no python3 with PyObjC found` | 安装 PyObjC,或用 `COMPUTER_USE_MCP_PYTHON` 指定解释器。 |
  246. | 工具列表为空 | 客户端配置里 `command` 必须是绝对路径;用 `--print-tools` 先确认服务能启动。 |
  247. | 权限显示 `true` 但仍无输入 | 权限授予的是启动服务的宿主程序;改完后重启宿主程序和 MCP 服务。 |
  248. | 截图全黑 / 失败 | 检查屏幕录制权限;锁屏时只能看到锁屏画面。 |
  249. | 中文输入失败 | 用 `type_text`(默认 `unicode`);某些 App 需要 `method: "keycode"` 输入 ASCII。 |
  250. | 快捷键没反应 | 确认目标 App 在前台;必要时先 `activate_app`。 |
  251. | 想看服务日志 | 客户端通常把 stderr 显示在 MCP 日志中;也可手动运行 `./bin/computer-use-mcp`。 |
  252. ## License
  253. MIT,见 [LICENSE](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.