desktop-hub

macOS 데스크톱 자동화를 위한 컴팩트 퍼사드 MCP 서버. 10개의 수제 도구(정의 약 2.3k 토큰)만 노출하고, 두 개의 풀 기능 컴퓨터 사용 MCP 서버 — cua-driver (56개 도구, 약 37k 토큰) 및 computer-use-mcp (64개 도구, 약 21k 토큰) — 와 네이티브 osascript에 지연 프록시합니다. 전체 120개 도구 표면을 유지하면서, 컨텍스트 창은 약 58k 대신 약 2k 토큰만 지불합니다.

아래에 설명 · Gitee 미러 (중국 내 미러) · Claude Code 및 모든 MCP 클라이언트와 호환됩니다.

이유

두 업스트림 서버를 직접 등록하면 세션당 도구 정의만으로 약 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

도구

사전 요구 사항

• 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가 알 수 없는 도구 오류를 반환하면, 먼저 desk_describe server:cua를 실행하여 도구 표면을 비교하세요.

• computer-use-mcp는 수동 설치 불필요 — npx가 첫 desk_call server:"oss" 시 @zavora-ai/computer-use-mcp@7.0.0을 자동으로 가져옵니다 (일회성 네트워크 액세스; 이후 몇 초의 스폰 지연 — 핸드셰이크 타임아웃은 이미 180초로 확장됨). 중국 본토 사용자는 npm 레지스트리 미러를 구성하는 것이 좋습니다.

macOS 권한

• CuaDriver.app에 손쉬운 사용(Accessibility) 및 화면 기록(Screen Recording) 권한 부여 (시스템 설정 → 개인정보 보호 및 보안) — cua-driver permissions grant를 실행하여 대화상자가 앱 ID에 귀속되도록 하세요 (그러면 권한이 업그레이드 후에도 유지됨). 이 권한이 없으면 모든 스크린샷/AX 호출이 불투명한 오류로 실패합니다.

• 터미널 / MCP 호스트 앱에도 동일한 두 권한 부여 — oss 백엔드는 호스트의 일반 node 자식 프로세스로 실행되며 TCC ID를 상속합니다.

• run_script는 첫 사용 시 대상 앱별로 macOS의 일회성 자동화(Automation) (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)하여 이 허브가 대신하도록 하세요. 새 설치에서는 이 단계를 건너뜁니다.

검증

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가 설치되고 권한이 부여되어 있어야 합니다 — 권한 없이 실패하는 것은 허브 버그가 아니라 설정 문제입니다.

환경 변수

설계 노트 및 함정 (피와 눈물로 얻은 교훈)

• 충돌한 백엔드는 자동으로 퇴출되고 다음 호출 시 재생성됩니다 (client.onclose 사용 — transport.onclose는 SDK에 의해 덮어써짐). 멈춘 백엔드: 호출이 RequestTimeout으로 실패하고 백엔드가 종료 + 재생성됩니다; desk_describe의 listTools 경로도 퇴출합니다. 모든 퇴출은 세대 가드(generation-guarded) 되어, 오래된 프로세스의 늦은 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: 언어는 대소문자를 구분하지 않으며 알 수 없는 값은 명시적으로 거부됩니다; 1MB/스트림을 초과하는 출력은 드레인됩니다 (스크립트는 완료까지 실행되고 부작용은 유지됨) 반환된 본문은 8KB로 잘리고 드롭된 바이트 수가 표시됩니다; 멀티바이트 CJK는 파이프 청크에서 분할되지 않습니다.

• SwiftUI 앱(예: 계산기)은 표시 값에 보이지 않는 문자(U+200E)를 포함할 수 있습니다 — verify의 value_equals는 unknown을 반환합니다; label_contains를 사용하거나 window_state 마크다운을 읽으세요.

• 두 차례의 다중 에이전트 대립 검토(21 + 20명의 검토자, 28개의 확인된 결함 수정 — 2차에서 1차 수정으로 도입된 두 개의 회귀를 발견)를 거쳤습니다. 회귀 테스트 스위트는 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 토큰의 10개 도구 정의로 cua-driver(56개 도구, 약 37k 토큰) + computer-use-mcp(64개 도구, 약 21k 토큰)의 합계 약 58k 토큰 컨텍스트 점유를 대체하며, 120개 기본 도구는 하나도 빠지지 않습니다(롱테일은 desk_call로 직접 접근, 스키마는 desk_describe로 필요 시 취득).

설치

전제: macOS, Node 18+, cua-driver(trycua/cua 공식 원클릭 스크립트로 설치, 위 영어 Prerequisites 참조, 설치 후 기본 경로가 이 허브의 기본 경로와 동일); 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"   # 必须绝对路径

국내 미러(동기화 업데이트, VPN 불필요): git clone https://gitee.com/zty552252kevin/desktop-hub.git

권한: CuaDriver.app에 「손쉬운 사용」+「화면 기록」 부여(권장: cua-driver permissions grant로 팝업이 App ID에 귀속되도록 하여 업그레이드 시 권한 유지); oss 백엔드는 호스트 터미널의 TCC ID를 따르므로 터미널에도 동일한 두 권한 부여; run_script는 첫 사용 시 대상 App별로 한 번 「자동화」 권한 팝업이 표시됩니다.

이전에 cua/oss 두 MCP 서버를 개별 등록했다면 비활성화하고 이 허브가 대신하도록 하세요; 새 설치에서는 이 단계를 건너뜁니다.

검증: npm test(20개 검사, 실제 데스크톱을 구동함; DESKTOP_HUB_TEST_OSS=1이면 oss 백엔드 포함). 환경 변수는 위 영어 표를 참조하세요.

함정 (피와 눈물로 얻은 교훈)

• 백엔드 충돌 시 자동 정리, 다음 호출 시 재생성(client.onclose에 의존, transport.onclose는 SDK에 의해 덮어써짐); 멈춘 백엔드는 해당 호출이 RequestTimeout으로 실패하고 종료 후 재생성되며, desk_describe의 listTools 타임아웃도 퇴출합니다. 모든 퇴출에는 세대 가드가 있습니다: 오래된 프로세스의 늦은 onclose가 갓 재생성된 새 클라이언트를 잘못 삭제하지 않습니다(그렇지 않으면 새 백엔드가 고아가 되고 element_token이 모두 무효화됨).

• 호스트 종료 시 두 백엔드에 연쇄 종료, 5초 제한 강제 종료, 핸드셰이크 중인 자식 프로세스도 종료됩니다(그렇지 않으면 npx 콜드 스타트 핸드셰이크 기간이 호스트 없는 허브를 180초 동안 유지할 수 있음).

• 호스트 취소(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 사용.

• 두 차례의 다중 에이전트 대립 검토(21+20명의 검토자)를 거쳐 총 28개의 확인된 결함 수정(2차에서 1차 수정으로 도입된 두 개의 회귀 발견).