使用说明

Claude KVM

Remote Access, Artificial Intelligence

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

[！提示] 幻影WG 这对你来说可能是一个很好的选择。 将您的VNC服务器隔离在您自己的网络中，同时享受自托管VPN性能以及在此过程中获得的额外隐私功能。

现场试运行

[！注意] 测试在GitHub Actions上透明地进行——每个步骤在CI环境中都是可见的。在每次测试结束时，无论集成是通过还是失败，您都会看到代理在会话期间采取的每个步骤的屏幕截图，以及 .mp4 捕获整个会话的视频录制。通过查看这些记录和屏幕截图，您可以观察代理在每个阶段的进展情况、任务花费的时间以及根据系统提示做出的决定。在您自己的环境中为MCP服务器制定自己的系统提示或说明时，您可以使用这些示例作为参考。

[！警告] 由于GitHub的工件保留政策，这些运行附带的工件可能已过期。永久副本是通过以下方式准备的持久文物工作流，始终可以通过运行ID从访问 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（苹果Silicon）	VNC连接、屏幕截图、鼠标/键盘输入注入	标准输入/标准输出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通过渐进式验证方法最大限度地降低了代币成本：

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。返回具有缩放空间中的边界框坐标的文本内容——实现精确的点击定位，而无需消耗视觉标记。

安装

需求

macOS（苹果Silicon/aarch64）
Node.js（LTS）

守护进程

brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

[！注意] claude-kvm-daemon 通过CI（GitHub Actions）进行编译和代码签名。构建输出以两种格式打包：a .tar.gz Homebrew发行档案和 .dmg 用于公证的磁盘映像。DMG在同一工作流程中提交给苹果服务器进行公证——该过程可以从CI日志中跟踪。经公证的DMG可作为CI文物使用；存档 .tar.gz 也作为版本发布在存储库上。Homebrew安装跟踪此版本。

发布 · 源代码

LibVNC构建 · LibVNC分行

自制水龙头

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?`	单击（左
`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`	单键按下（输入
`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身份验证 --基于密码的质询响应（DES）
德国广播联盟 --苹果远程桌面（Diffie-Hellman+AES-128-ECB）

macOS通过ARD身份验证类型30凭据请求自动检测。检测到时，元键将重新映射到超级（命令键兼容性）。

[！注意] 在裸机Mac上运行？看 Mac M1准备技巧用于VNC强化、SSH隧道和会话稳定性提示。

“克劳德”是Anthropic，PBC的商标。本项目不隶属于Anthropic或得到Anthropics的认可。

使用说明

Claude KVM

现场试运行

建筑

图层

PC（过程调用）协议

坐标缩放

屏幕策略

安装

需求

守护进程

MCP配置

配置

MCP代理（ENV）

后台程序参数（CLI）

运行时配置（PC）

工具

屏幕

老鼠

键盘

检测

配置

控制

认证

相关 MCP

远程MacOS控制服务器

终端命令执行服务器

AI桌面自动化工具

视频播放控制服务器

SFTP-SSH MCP服务器

AI智能体计算机使用平台