desktop-hub

macOS デスクトップ自動化のためのコンパクトなファサード MCP サーバー。 手書きのツールはわずか 10 個（定義は約 2.3k トークン）で、2 つのフル機能の computer-use MCP サーバー — cua-driver（56 ツール、約 37k トークン）と computer-use-mcp（64 ツール、約 21k トークン）— に加えてネイティブの osascript に遅延プロキシします。120 ツールの全表面を維持しつつ、コンテキストウィンドウは約 58k トークンではなく約 2k トークンしか消費しません。

中文说明在下方 · Gitee mirror 国内镜像 · Claude Code および任意の MCP クライアントで動作します。

Why

両方のアップストリームサーバーを直接登録すると、ツール定義だけでセッションあたり約 58k のコンテキストトークンを消費しますが、高頻度で使う表面は小さいものです。このファサードは、ホットパスを安価に保ち、ロングテールにも到達可能にします：

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

Tools

Prerequisites

• macOS（Apple Silicon または Intel）、Node.js 18+（Node 26 で開発）。

• cua-driver — trycua/cua プロジェクトの macOS ドライバー（libs/cua-driver）。公式のワンライナーでインストールすると、CuaDriver.app が /Applications に配置され、~/.local/bin/cua-driver にシンボリックリンクが作成されます（このハブのデフォルトパスと完全に一致 — 設定は不要）：

  /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 permissions

• CuaDriver.app に「アクセシビリティ」と「画面収録」（システム設定 → プライバシーとセキュリティ）を許可します — cua-driver permissions grant を実行すると、ダイアログがアプリの ID に帰属するようになります（許可はアップグレード後も維持されます）。これがないと、すべてのスクリーンショット/AX 呼び出しが不透明なエラーで失敗します。

• 同じ 2 つをターミナル / MCP ホストアプリにも許可します — oss バックエンドはホストのプレーンな node 子プロセスとして実行され、その TCC アイデンティティを継承します。

• run_script は、初回使用時に macOS の一度きりの自動化（Apple Events）プロンプトをターゲットアプリごとにトリガーします。

Install & register

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）して、このハブが引き継ぐようにします。新規インストールではこの手順は不要です。

Verify

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 がインストールされ、権限が付与されていることを前提としています — それらがない場合の失敗はセットアップの問題であり、ハブのバグではありません。

Environment variables

Design notes & pitfalls (hard-won)

• クラッシュしたバックエンドは自動的に排除され、次の呼び出しで再生成されます（client.onclose 経由 — transport.onclose は SDK によって上書きされます）。ハングしたバックエンド：呼び出しは RequestTimeout で失敗し、バックエンドは強制終了 + 再生成されます。desk_describe の listTools パスも同様に排除します。すべての排除は世代ガード付きで、古いプロセスからの遅延 onclose が新しく再生成されたクライアントを削除することは決してありません（そうなるとクライアントが孤立し、すべての element_token が失われます）。

• ホストの終了（stdin EOF / SIGTERM / SIGINT）は両方のバックエンドにシャットダウンをカスケードし、5 秒で制限されます — ハンドシェイク中の npx コールドスタートが、ホストのないハブを 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 を保持してはいけません — ファサードが自動的に削除します。マルチウィンドウアプリでのピクセルパスのドラッグ/スクロールには 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 アプリ（例：Calculator）は表示値に不可視文字（U+200E）を埋め込むことがあります — その場合 verify の value_equals は unknown を返します。代わりに label_contains を使用するか、window_state のマークダウンを読んでください。

• 2 ラウンドのマルチエージェント対抗レビュー（21 + 20 人のレビュアー、28 件の確認済み欠陥を修正 — ラウンド 2 ではラウンド 1 の修正によって導入された 2 件の回帰を検出）。回帰スイートは test/smoke.mjs にあります。

Third-party tools

desktop-hub は、2 つの独立して開発されたツールを別々の 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" はそれぞれの所有者の名称/商標であり、ツールを識別するために名目的に使用されています。このプロジェクトはどちらとも提携しておらず、承認も受けていません。

License

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 项确认缺陷（第二轮抓出第一轮两个修复自身引入的回归）。