desktop-hub

一个面向 macOS 桌面自动化的精简门面 MCP 服务器。 它只暴露 10 个手写工具（约 2.3k token 的定义），并惰性代理到两个功能完备的 computer-use MCP 服务器 —— cua-driver（56 个工具，约 37k token）和 computer-use-mcp（64 个工具，约 21k token）—— 外加原生 osascript。你保留了全部 120 个工具面，但你的上下文窗口只需支付约 2k token，而不是约 58k。

中文说明在下方 · Gitee 镜像（国内镜像） · 适用于 Claude Code 和任何 MCP 客户端。

为什么

直接注册两个上游服务器，每个会话仅工具定义就要消耗约 58k 上下文 token，而高频工具面其实很小。这个门面让热路径保持廉价，同时长尾仍然可达：

MCP client ──stdio──> desktop-hub (this server, 10 compact tools)
                        ├─ lazy stdio child ──> cua-driver mcp        (background desktop control, no cursor/focus steal)
                        ├─ lazy stdio child ──> computer-use-mcp      (AX tree, find_element, fill_form, Spaces…; spawned on first use)
                        └─ local osascript                            (AppleScript/JXA, true background scripting)

Related MCP server: Computer Use MCP Server

工具

前置条件

• macOS（Apple Silicon 或 Intel）、Node.js 18+（在 Node 26 上开发）。

• cua-driver —— 来自 trycua/cua 项目的 macOS 驱动（libs/cua-driver）。用他们的官方一行命令安装，该命令会把 CuaDriver.app 放到 /Applications，并符号链接 ~/.local/bin/cua-driver（正是本 hub 的默认路径 —— 无需配置）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

文档：https://cua.ai/docs/how-to-guides/driver/install。已针对 cua-driver 0.20.0（cua-driver --version）测试；如果驱动升级后 act/verify 返回 unknown-tool 错误，先运行 desk_describe server:cua 对比工具面。

• computer-use-mcp 无需手动安装 —— 首次 desk_call server:"oss" 时 npx 会自动拉取 @zavora-ai/computer-use-mcp@7.0.0（一次性联网；之后有数秒的启动延迟 —— 握手超时已放宽到 180 秒）。中国大陆用户可考虑配置 npm 镜像。

macOS 权限

授予 CuaDriver.app「辅助功能」和「屏幕录制」权限（系统设置 → 隐私与安全性）—— 运行 cua-driver permissions grant，让弹窗归属到应用身份（这样授权在升级后仍然有效）。没有这些权限，每次截图/AX 调用都会以不透明的错误失败。

同样授予你的终端 / MCP 宿主应用这两项权限 —— oss 后端作为宿主的普通 node 子进程运行，继承其 TCC 身份。

run_script 在首次使用时，会针对每个目标应用触发 macOS 的一次性「自动化」（Apple Events）授权提示。

安装与注册

git clone https://github.com/zty552252kevin-code/desktop-hub.git
cd desktop-hub
npm ci        # not `npm install` — the code relies on SDK 1.30.0 internals pinned in the lockfile
claude mcp add desktop-hub -s user -- node "$(pwd)/server.mjs"   # path must be absolute

中国大陆镜像（保持同步）：git clone https://gitee.com/zty552252kevin/desktop-hub.git

仅当你之前把 cua-driver 或 computer-use-mcp 注册为独立 MCP 服务器时：禁用这些条目（例如 ~/.claude.json 中的 disabledMcpServers），让本 hub 接管。全新安装可跳过此步骤。

验证

npm test                        # 20 checks; spawns the real driver and runs osascript on your desktop
DESKTOP_HUB_TEST_OSS=1 npm test # also exercises the oss backend (slow first npx spawn, needs network)

该套件要求已安装 cua-driver 并授予权限 —— 没有这些前提的失败属于环境配置问题，而非 hub 的 bug。

环境变量

设计说明与坑（血泪换来的）

• 崩溃的后端会被自动驱逐，并在下次调用时重生（通过 client.onclose —— transport.onclose 会被 SDK 覆写）。假死后端：调用以 RequestTimeout 失败，后端被杀死并重生；desk_describe 的 listTools 路径也会驱逐。所有驱逐都带代际守卫，因此旧进程迟到的 onclose 永远不会删除刚重生的客户端（否则会使其孤儿化，并让所有 element_token 失效）。

• 宿主退出（stdin EOF / SIGTERM / SIGINT）会级联关停两个后端，限时 5 秒 —— 握手中的 npx 冷启动无法让无宿主的 hub 存活 180 秒的握手窗口；仍在连接的子进程会被强制杀死。

• 宿主侧取消（例如 Claude Code 中的 Esc）会真正中止：中止信号被传入上游 callTool 并杀死 osascript 子进程，因此取消后排队的点击/脚本绝不会落到真实桌面。

• act：double_click/right_click/set_value/menu 必须带 pid（上游硬性要求 —— 仅有 element_token 不够）；桌面级双击 = action:"click" + extra:{count:2}。scope:"desktop" 不得携带 pid/window_id —— facade 会自动剔除。多窗口应用上的像素路径拖拽/滚动需要 window_id，否则上游会以歧义为由拒绝。无目标滚动（仅 pid）会向焦点控件发送方向键/PageDown 键 —— 传入 element_token 或 x,y 可在指定位置滚轮滚动。

• 不同后端的坐标系不同：desktop_screenshot 返回真实屏幕像素（Retina 上为 2x）—— 适用于 cua scope:"desktop"；通过 desk_call 调用的 oss 指针工具使用逻辑点（1x）。除以返回的缩放因子，或从 desk_call oss screenshot 取坐标。

• run_script：language 大小写不敏感，未知值会明确报错；输出超过 1MB/流式输出会被排空（脚本会运行完毕，副作用完整保留），而返回的正文被裁剪到 8KB 并附丢弃字节的说明；多字节 CJK 不会在管道块间被拆开。

• SwiftUI 应用（如计算器）可能在显示值中嵌入不可见字符（U+200E）—— 此时 verify 的 value_equals 会返回 unknown；请改用 label_contains 或读取 window_state 的 markdown。

• 经过两轮多 agent 对抗评审（21 + 20 位审查员，修复 28 个确认缺陷 —— 第二轮抓到了第一轮修复引入的两个回归）。回归套件位于 test/smoke.mjs。

第三方工具

desktop-hub 是一个门面，将两个独立开发的工具作为独立的 MCP 服务器进程启动；它们不包含在本仓库中，由你单独安装：

• cua-driver (CuaDriver.app, com.trycua.driver) — MIT, © Cua AI, Inc. — https://github.com/trycua/cua

• @zavora-ai/computer-use-mcp — MIT, © Zavora Technologies Ltd. — https://github.com/zavora-ai/computer-use-mcp

"cua"、"CuaDriver" 和 "Zavora" 是其各自所有者的名称/商标，此处以指名方式用于标识工具；本项目与它们均无关联，也未获得任何一方的认可。

许可证

MIT

中文说明

macOS 桌面自动化的精简聚合 MCP 服务器：用 ~2.3k token 的 10 个工具定义，替代 cua-driver（56 工具 ~37k token）+ computer-use-mcp（64 工具 ~21k token）合计 ~58k token 的上下文占用，120 个底层工具一个不少（长尾经 desk_call 直达、schema 用 desk_describe 按需取）。

安装

前置：macOS、Node 18+、cua-driver（用 trycua/cua 官方一键脚本装，见上方英文 Prerequisites，装完默认路径即本 hub 默认路径）；oss 后端无需手装，首次 desk_call server:"oss" 时 npx 自动拉取 @zavora-ai/computer-use-mcp@7.0.0（首次需联网，大陆用户建议配 npm 镜像）。

git clone https://github.com/zty552252kevin-code/desktop-hub.git
cd desktop-hub
npm ci
claude mcp add desktop-hub -s user -- node "$(pwd)/server.mjs"   # 必须绝对路径

国内镜像（同步更新，免翻墙）：git clone https://gitee.com/zty552252kevin/desktop-hub.git

权限：给 CuaDriver.app 授予「辅助功能」+「屏幕录制」（推荐 cua-driver permissions grant 让弹窗归属到 App 身份，升级不掉权限）；oss 后端跟随宿主终端的 TCC 身份，终端也要授同样两项；run_script 首次对每个目标 App 会弹一次「自动化」授权。

此前如果单独注册过 cua/oss 两个 MCP 服务器，把它们 disable 掉由本 hub 接管；全新安装跳过这步。

验证：npm test（20 项检查，会真实驱动桌面；DESKTOP_HUB_TEST_OSS=1 含 oss 后端）。环境变量见上方英文表格。

坑（血泪换来的）

• 后端崩溃自动清理、下次调用重生（依赖 client.onclose，transport.onclose 会被 SDK 覆写）；假死后端该次调用报 RequestTimeout 并杀掉重生，desk_describe 的 listTools 超时同样驱逐。所有驱逐带代际守卫：旧进程迟到的 onclose 不会误删刚重生的新 client（否则孤儿化新后端 + element_token 全部失效）。

• 宿主退出级联关停两个后端、限时 5s 强退，握手中的子进程也会被补刀（否则 npx 冷启动握手期能把无宿主 hub 拖 180s）。

• 宿主取消（Esc）真正中止：信号贯通到上游 callTool 和 osascript 子进程，取消后排队的点击/脚本不会再落到真桌面。

• act：double_click/right_click/set_value/menu 必须带 pid（上游硬性要求）；scope:"desktop" 禁止携带 pid/window_id（facade 自动剔除）；多窗口应用的像素 drag/scroll 必须带 window_id；无目标 scroll 走键击路径（发给焦点控件），要滚指定区域必须给 element_token 或 x,y。

• 坐标系不同：desktop_screenshot 是 Retina 真像素（2x），cua desktop-scope 用它；oss 指针工具用逻辑坐标（1x），要除以 scale factor 或从 desk_call oss screenshot 取坐标。

• run_script：language 大小写不敏感、未知值明确报错；输出超 1MB 不杀脚本（继续排水跑完、副作用完整），回传剪裁到 8KB 并标注丢弃量；中文跨管道块不出乱码。

• SwiftUI 应用显示值可能带 U+200E 隐形字符，verify 的 value_equals 会 unknown，改用 label_contains。

• 经两轮多 agent 对抗评审（21+20 个审查员）累计修复 28 项确认缺陷（第二轮抓出第一轮两个修复自身引入的回归）。