Claude KVM
官方🤖 ⚡️ MCP 伺服器（ MacOS）— 透過 VNC 控制遠端桌面
文件
Claude KVM
遠端存取、人工智慧
Claude KVM 是一個透過 VNC 控制遠端桌面環境的 MCP 工具。它由一個輕量的 JS 代理層（MCP 伺服器）和一個在 macOS 系統上執行的平台原生 Swift VNC 守護程式所組成。
[!TIP] Phantom-WG 可能是您絕佳的替代方案。 將您的 VNC 伺服器隔離在自有網路中，同時享受自託管的 VPN 效能，並獲得額外的隱私保護功能。
即時測試執行
- 整合測試
- Mac 整合測試
- Mac 計算機測試
- Mac 科學計算機測試
- Mac Safari 瀏覽測試
- Mac 拖放測試
- Mac 西洋棋測試
- Mac 西洋棋直接測試
- Mac Phantom-WG 安裝測試
[!NOTE] 測試在 GitHub Actions 上透明地進行——CI 環境中的每個步驟都可見。在每次測試結束時，無論整合測試通過與否，您都會找到代理在會話期間每個步驟的螢幕截圖，以及一個記錄整個會話的
.mp4影片。透過檢視這些錄影和螢幕截圖，您可以觀察代理如何推進每個階段、任務花費了多長時間，以及根據系統提示做出了哪些決策。在您為自己的環境中的 MCP 伺服器製作系統提示或指令時，可以將這些範例作為參考。
[!WARNING] 由於 GitHub 的成品保留政策，附加到這些執行的成品可能已過期。持久性副本會透過 Persist Artifacts 工作流程準備，並始終可以透過執行 ID 從 press-kit 分支上的
artifacts/目錄存取。
架構
graph TB
subgraph MCP["MCP Client (Claude)"]
AI["Claude"]
end
subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
direction TB
Server["MCP Server<br/><code>index.js</code>"]
Tools["Tool Definitions<br/><code>tools/index.js</code>"]
Server --> Tools
end
subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
direction TB
CMD["Command Handler<br/><i>PC Dispatch</i>"]
Scale["Display Scaling<br/><i>Scaled ↔ Native</i>"]
subgraph Screen["Screen"]
Capture["Frame Capture<br/><i>PNG · Crop · Diff</i>"]
OCR["OCR Detection<br/><i>Apple Vision</i>"]
end
subgraph InputGroup["Input"]
Mouse["Mouse<br/><i>Click · Drag · Move · Scroll</i>"]
KB["Keyboard<br/><i>Tap · Combo · Type · Paste</i>"]
end
VNC["VNC Bridge<br/><i>LibVNCClient 0.9.15</i>"]
CMD --> Scale
Scale --> Capture
Scale --> Mouse
Scale --> KB
Capture -.->|"framebuffer"| VNC
Mouse -->|"pointer events"| VNC
KB -->|"key events"| VNC
end
subgraph Target["Target Machine"]
VNC_Server["VNC Server<br/><i>:5900</i>"]
Desktop["Desktop Environment"]
VNC_Server --> Desktop
end
AI <-->|"stdio<br/>JSON-RPC"| Server
Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server
classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
classDef target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5
class Server,Tools proxy
class CMD,Scale,VNC,Capture,Mouse,KB daemon
class VNC_Server,Desktop target
分層
| 層級 | 語言 | 角色 | 通訊方式 |
|---|---|---|---|
| MCP 代理 | JavaScript (Node.js) | 透過 MCP 協定與 Claude 通訊，管理守護程式生命週期 | stdio JSON-RPC |
| VNC 守護程式 | Swift/C (Apple Silicon) | VNC 連線、螢幕擷取、滑鼠/鍵盤輸入注入 | stdin/stdout PC (NDJSON) |
PC（程序呼叫）協定
代理與守護程式之間的通訊使用基於 NDJSON 的 PC 協定：
Request: {"method":"<name>","params":{...},"id":<int|string>}
Response: {"result":{...},"id":<int|string>}
Error: {"error":{"code":<int>,"message":"..."},"id":<int|string>}
Notification: {"method":"<name>","params":{...}}
座標縮放
VNC 伺服器的原生解析度會縮小以符合 --max-dimension（預設：1280px）。Claude 在使用縮放後的座標時表現更為一致——守護程式會在背景處理轉換：
Native: 4220 x 2568 (VNC server framebuffer)
Scaled: 1280 x 779 (what Claude sees and targets)
mouse_click(640, 400) → VNC receives (2110, 1284)
螢幕策略
Claude 透過漸進式驗證方法將 token 成本降至最低：
diff_check → changeDetected: true/false ~5ms (text only, no image)
detect_elements → OCR text + bounding boxes ~50ms (text only, no image)
cursor_crop → crop around cursor ~50ms (small image)
screenshot → full screen capture ~200ms (full image)
detect_elements 使用 Apple Vision 框架進行裝置端 OCR。傳回包含縮放空間中邊界框座標的文字內容——能夠在不消耗視覺 token 的情況下實現精確的點擊定位。
安裝
需求
- macOS (Apple Silicon / aarch64)
- Node.js (LTS)
守護程式
brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon
[!NOTE]
claude-kvm-daemon是透過 CI (GitHub Actions) 編譯並進行程式碼簽署的。建置輸出以兩種格式打包：用於 Homebrew 發佈的.tar.gz封存檔，以及用於公證的.dmg磁碟映像檔。DMG 會在同一個工作流程中提交至 Apple 伺服器進行公證——可以從 CI 日誌追蹤此過程。已公證的 DMG 可作為 CI 成品取得；已封存的.tar.gz也會作為版本發佈在儲存庫中。Homebrew 安裝會追蹤此版本。
MCP 設定
在您的專案目錄中建立一個 .mcp.json 檔案：
{
"mcpServers": {
"claude-kvm": {
"command": "npx",
"args": ["-y", "claude-kvm"],
"env": {
"VNC_HOST": "192.168.1.100",
"VNC_PORT": "5900",
"VNC_USERNAME": "user",
"VNC_PASSWORD": "pass",
"CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
"CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
}
}
}
}
[!NOTE] 此工具透過 CI 進行端對端測試——Claude 透過 VNC 執行任務，同時一個獨立的視覺模型會觀察並驗證結果。請參閱 整合測試 以取得即時工作流程執行、系統提示和示範錄影。
設定
MCP 代理 (ENV)
| 參數 | 預設 | 說明 |
|---|---|---|
VNC_HOST | 127.0.0.1 | VNC 伺服器位址 |
VNC_PORT | 5900 | VNC 連接埠號碼 |
VNC_USERNAME | 使用者名稱（ARD 需要） | |
VNC_PASSWORD | 密碼 | |
CLAUDE_KVM_DAEMON_PATH | claude-kvm-daemon | 守護程式二進位檔路徑（若已在 PATH 中則不需要） |
CLAUDE_KVM_DAEMON_PARAMETERS | 傳遞給守護程式的額外 CLI 引數 |
守護程式參數 (CLI)
透過 CLAUDE_KVM_DAEMON_PARAMETERS 傳遞給守護程式的額外引數：
"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"
| 參數 | 預設 | 說明 |
|---|---|---|
--max-dimension | 1280 | 最大顯示縮放尺寸 (px) |
--connect-timeout | VNC 連線逾時（秒） | |
--bits-per-sample | 每像素取樣位元數 | |
--no-reconnect | 停用自動重新連線 | |
-v, --verbose | 詳細記錄（stderr） |
執行階段設定 (PC)
所有計時和顯示參數都可以在執行階段透過 configure 方法進行設定。使用 get_timing 來檢查目前的值。
設定計時：
{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}
{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}
變更顯示縮放：
{"method":"configure","params":{"max_dimension":960}}
{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}
重設為預設值：
{"method":"configure","params":{"reset":true}}
{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}
取得目前的值：
{"method":"get_timing"}
{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}
| 參數 | 預設 | 說明 |
|---|---|---|
max_dimension | 1280 | 最大螢幕截圖尺寸 |
cursor_crop_radius | 150 | 游標裁切半徑 (px) |
click_hold_ms | 50 | 點擊按住持續時間 |
double_click_gap_ms | 50 | 雙擊間隔延遲 |
hover_settle_ms | 400 | 懸停穩定等待 |
drag_position_ms | 30 | 拖曳前定位等待 |
drag_press_ms | 50 | 拖曳按下保持閾值 |
drag_step_ms | 5 | 內插點之間 |
drag_settle_ms | 30 | 釋放前穩定 |
drag_pixels_per_step | 20 | 每像素點密度 |
drag_min_steps | 10 | 最小內插步驟 |
scroll_press_ms | 10 | 滾輪按下釋放間隔 |
scroll_tick_ms | 20 | 刻度間延遲 |
key_hold_ms | 30 | 按鍵按住持續時間 |
combo_mod_ms | 10 | 修飾鍵穩定延遲 |
type_key_ms | 20 | 輸入期間按鍵按住 |
type_inter_key_ms | 20 | 字元間延遲 |
type_shift_ms | 10 | Shift 鍵穩定 |
paste_settle_ms | 30 | 剪貼簿寫入後等待 |
工具
所有操作都透過單一的 vnc_command 工具執行：
螢幕
| 動作 | 參數 | 說明 |
|---|---|---|
screenshot | 全螢幕 PNG 擷取 | |
cursor_crop | 圍繞游標裁切並疊加十字線 | |
diff_check | 針對基準線偵測螢幕變更 | |
set_baseline | 將目前螢幕儲存為差異參考 |
滑鼠
| 動作 | 參數 | 說明 |
|---|---|---|
mouse_click | x, y, button? | 點擊（左|右|中） |
mouse_double_click | x, y | 雙擊 |
mouse_move | x, y | 移動游標 |
hover | x, y | 移動 + 穩定等待 |
nudge | dx, dy | 相對游標移動 |
mouse_drag | x, y, toX, toY | 從起點拖曳到終點 |
scroll | x, y, direction, amount? | 滾動（上|下|左|右） |
鍵盤
| 動作 | 參數 | 說明 |
|---|---|---|
key_tap | key | 單鍵按下（enter|escape|tab|space|...） |
key_combo | key 或 keys | 修飾鍵組合（"cmd+c" 或 ["cmd","shift","3"]） |
key_type | text | 逐字輸入文字 |
paste | text | 透過剪貼簿貼上文字 |
偵測
| 動作 | 參數 | 說明 |
|---|---|---|
detect_elements | 帶有邊界框的 OCR 文字偵測（Apple Vision） |
傳回縮放空間中帶有邊界框座標的文字元素：
{"method":"detect_elements"}
{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}
設定
| 動作 | 參數 | 說明 |
|---|---|---|
configure | {<params>} | 在執行階段設定計時/顯示參數 |
configure | {reset: true} | 將所有參數重設為預設值 |
get_timing | 取得目前的計時 + 顯示參數 |
控制
| 動作 | 參數 | 說明 |
|---|---|---|
wait | ms? | 等待（預設 500ms） |
health | 連線狀態 + 顯示資訊 | |
shutdown | 優雅地關閉守護程式 |
驗證
支援的 VNC 驗證方法：
- VNC Auth — 基於密碼的挑戰-回應（DES）
- ARD — Apple 遠端桌面（Diffie-Hellman + AES-128-ECB）
macOS 會透過 ARD 驗證類型 30 的憑證請求自動偵測。偵測到時，Meta 鍵會重新對應為 Super（Command 鍵相容性）。
[!NOTE] 在裸機 Mac 上執行嗎？請參閱 Mac M1 準備技巧，了解 VNC 強化、SSH 隧道與工作階段穩定性提示。
「Claude」是 Anthropic, PBC 的商標。本專案與 Anthropic 無關，亦未獲其背書。
Copyright (c) 2026 Riza Emre ARAS — MIT License