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 无关联，亦未获其认可。
版权所有 (c) 2026 Riza Emre ARAS — MIT 许可证