Claude KVM

Claude KVM

远程访问，人工智能

claude-kvm.ai

Claude KVM 是一种 MCP 工具，可通过 VNC 控制远程桌面环境。它由一个轻量级 JS 代理层（MCP 服务）和一个运行在 macOS 系统上的平台原生 Swift VNC 守护进程组成。

提示

**Phantom-WG 或许是一个很好的替代方案。**在您自己的网络中隔离 VNC 服务，同时享受可自托管 VPN 的性能，以及由此带来的额外隐私保护功能。

实时测试运行

• 集成测试
• Mac 集成测试
• Mac 计算器测试
• Mac 科学计算器测试
• Mac Safari 浏览测试
• Mac 拖放测试
• Mac 国际象棋测试
• Mac 国际象棋直接测试
• Mac Phantom-WG 安装测试

说明

测试在 GitHub Actions 上透明进行——CI 环境中的每个步骤都清晰可见。每次测试结束时，无论集成成功还是失败，您都能找到 Agent 在会话中每一步操作的截图，以及一段记录整个会话的 .mp4 视频。通过查看这些录像和截图，您可以了解 Agent 如何逐步完成各个阶段、任务耗时多久，以及它根据系统提示词做出了哪些决定。您可以将这些示例作为参考，为自己的环境编写系统提示词或 MCP 服务指令。

警告

由于 GitHub 的制品保留政策，这些运行所附的制品可能已过期。我们通过 Persist Artifacts 工作流准备了持久副本，您也可以随时在 press-kit 分支的 artifacts/ 目录中通过运行 ID 访问这些副本。

架构

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

说明

claude-kvm-daemon 通过 CI（GitHub Actions）编译并进行代码签名。构建输出打包为两种格式：用于 Homebrew 分发的 .tar.gz 归档文件，以及用于公证的 .dmg 磁盘映像。DMG 会在同一工作流中提交至 Apple 服务器进行公证，可通过 CI 日志跟踪此过程。经过公证的 DMG 可作为 CI Artifact 获取；归档后的 .tar.gz 也会作为仓库的一个发行版本发布。Homebrew 安装会跟踪此发行版本。

• 发行版本 · 源代码
• LibVNC 构建 · LibVNC 分支
• Homebrew Tap

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"
      }
    }
  }
}

说明

此工具已通过 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?	点击（left|right|middle）
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?	滚动（up|down|left|right）

键盘

操作	参数	说明
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 Remote Desktop（Diffie-Hellman + AES-128-ECB）

通过 ARD 身份验证类型 30 的凭据请求自动检测 macOS。检测到后，Meta 键会重新映射为 Super（兼容 Command 键）。

---

说明

在裸机 Mac 上运行？请参阅 Mac M1 准备技巧，了解 VNC 加固、SSH 隧道和会话稳定性技巧。

---

“Claude”是 Anthropic, PBC 的商标。本项目与 Anthropic 无关，也未获得其认可。

版权所有 (c) 2026 Riza Emre ARAS — MIT 许可证