Claude Kvm

Claude KVM

Remote Access, Artificial Intelligence

claude-kvm.ai

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

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

现场试运行

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

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

\[！警告\]

建筑

graph TB
    subgraph MCP["MCP Client (Claude)"]
        AI["Claude"]
    end

    subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
        direction TB
        Server["MCP Server
index.js"]
        Tools["Tool Definitions
tools/index.js"]
        Server --> Tools
    end

    subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
        direction TB
        CMD["Command Handler
PC Dispatch"]
        Scale["Display Scaling
Scaled ↔ Native"]

        subgraph Screen["Screen"]
            Capture["Frame Capture
PNG · Crop · Diff"]
            OCR["OCR Detection
Apple Vision"]
        end

        subgraph InputGroup["Input"]
            Mouse["Mouse
Click · Drag · Move · Scroll"]
            KB["Keyboard
Tap · Combo · Type · Paste"]
        end

        VNC["VNC Bridge
LibVNCClient 0.9.15"]

        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
:5900"]
        Desktop["Desktop Environment"]
        VNC_Server --> Desktop
    end

    AI |"stdio
JSON-RPC"| Server
    Server |"stdin/stdout
PC (NDJSON)"| CMD
    VNC |"RFB Protocol
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

图层

PC（过程调用）协议

代理和守护进程之间的通信使用NDJSON上的PC协议：

Request:      {"method":"","params":{...},"id":}
Response:     {"result":{...},"id":}
Error:        {"error":{"code":,"message":"..."},"id":}
Notification: {"method":"","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安装跟踪此版本。 - 自制水龙头

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）

后台程序参数（CLI）

通过以下方式传递给守护进程的其他参数 CLAUDE_KVM_DAEMON_PARAMETERS:

"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"

运行时配置（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}}

______________________________________________________________________

工具

所有操作都是通过单个 vnc_command 工具：

屏幕

老鼠

键盘

检测

返回缩放空间中具有边界框坐标的文本元素：

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

配置

控制

______________________________________________________________________

认证

支持的VNC身份验证方法：

• VNC身份验证 --基于密码的质询响应（DES）
• 德国广播联盟 --苹果远程桌面（Diffie-Hellman+AES-128-ECB）

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

______________________________________________________________________

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

______________________________________________________________________

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

版权所有（c）2026 Riza Emre ARAS-MIT许可证