内容
# jetkvm-mcp
**赋予人工智能在物理计算机上看到和操作的能力**
jetkvm-mcp 是一个 [MCP](https://modelcontextprotocol.io) 服务器，它将 [JetKVM](https://jetkvm.com)——一个小型开源的 KVM-over-IP 设备——转变为一台机器，Claude（或任何 MCP 客户端）可以直接看到和操作：观看屏幕，输入，点击，挂载启动媒体，控制电源。因为 JetKVM 位于 HDMI 和 USB 端口上，人工智能驱动计算机 **在操作系统以下** —— BIOS 屏幕，引导加载程序，安装程序，无网络的无头盒，卡住的机器。无需代理，无需 SSH，目标上无需安装任何东西。
```
你： "截图。机器卡住了 - 怎么了？"
claude: → 截图 → "它停在 GRUB 救援提示符下。根分区 UUID 更改了。您要我手动启动它吗？" → 输入文本 → 回车 → 修复
```
与 **股票 JetKVM 固件** 配合使用 —— 无需修改设备。
## 两个层面
|层面 | 工具 | 性质 |
|-------|-------|--------|
| **屏幕控制** （眼睛 + 手） | `截图`，`点击`，`双击`，`移动鼠标`，`输入文本`，`按键`，`滚动` | 视觉循环 —— 人工智能观察，然后行动 |
| **设备控制** | `挂载媒体网址`，`挂载媒体存储`，`上传媒体`，`上传并挂载`，`卸载媒体`，`列出存储`，`删除存储文件`，`存储空间`，`虚拟媒体状态`，`电源`，`电源状态`，`直流电源`，`唤醒主机`，`唤醒网络`，`USB 仿真`，`视频状态`，`重启设备` | 确定性 RPC |
完整参数参考：[docs/tools.md](docs/tools.md)。
## 工作原理
与设备的单个 WebRTC 对等连接驱动一切：
```
克劳德 ──MCP/stdio──▶ server.py （此仓库，在你的工作站上运行）
│
└──WebRTC 通过 LAN ──▶ JetKVM ──HDMI-in / USB-HID-out ──▶ 目标机器
├─ H.264 视频轨道 ─▶ 在本地解码（PyAV） ─▶ JPEG 截图
└─ “rpc” 数据通道 ─▶ 键盘 / 鼠标 / 媒体 / 电源 JSON-RPC
```
- 设备已经将 HDMI 捕获作为 H.264 视频轨道流式传输 — 客户端在本地解码并按需为 AI 提供 JPEG 快照。（JetKVM 没有快照端点；它不需要。）
- 可靠的 `rpc` 数据通道承载设备的 Web UI 使用的每个 JSON-RPC 方法：
`keyboardReport`，`absMouseReport` （绝对 0–32767，无漂移），`mountWithHTTP`，
`setATXPowerAction` 等。
- 服务器在第一次工具调用时延迟连接，并保持连接。
深入探讨 — 握手，编解码器协商，关键帧/PLI 故事，坐标映射：
[docs/architecture.md](docs/architecture.md)。
## 要求
- 一个连接到目标机器的 JetKVM，在你的网络中可访问
- 运行克劳德的机器上的 Python 3.11+
- `aiortc`/`av` 轮子捆绑了 macOS/Linux 上的 FFmpeg；如果触发从源代码构建，
请先安装 FFmpeg 开发库（`brew install ffmpeg` / `apt install libavdevice-dev`）
## 快速入门
```bash
git clone https://github.com/shvartzj1/jetkvm-mcp.git
cd jetkvm-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 设置 JETKVM_URL （+ JETKVM_PASSWORD 如果您的设备有）
```
在将其连接到任何内容之前，先测试管道 — 这将连接，维持流畅，并保存四张截图：
```bash
set -a; source .env; set +a
python smoke_test.py
```
预期输出 — 持续 ~60 fps，第一张后的毫秒级快照：
```
connected. video_state: {'ready': True, 'width': 1280, 'height': 1024, 'fps': 60}
snapshot 0: 1280x1024 179578 bytes （grab 3129 ms） frames_seen=1
snapshot 1: 1280x1024 178280 bytes （grab 11 ms） frames_seen=128
...
```
## 连接到克劳德
**克劳德代码** （一条命令，在每个会话中可用）：
```bash
claude mcp add jetkvm --scope user \
--env JETKVM_URL=http://192.168.1.50 \
--env JETKVM_VERIFY_TLS=false \
-- /abs/path/jetkvm-mcp/.venv/bin/python /abs/path/jetkvm-mcp/server.py
```
**克劳德桌面** （`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"jetkvm": {
"command": "/abs/path/jetkvm-mcp/.venv/bin/python",
"args": ["/abs/path/jetkvm-mcp/server.py"],
"env": {
"JETKVM_URL": "http://192.168.1.50",
"JETKVM_PASSWORD": "",
"JETKVM_VERIFY_TLS": "false"
}
}
}
}
```
然后直接与它对话： *"截图，打开终端，检查磁盘使用情况。"*
人工智能调用 `截图` → 推理 → `点击` / `输入文本` → 重复。
## 杀手级工作流程：无人工干预的裸机配置
设备控制和屏幕控制组合成某种在-OS 代理无法做到的事情 — 在空机器上安装操作系统：
```
mount_media_url("https://mirror.lan/rocky-9.iso", "CDROM") # 自己托管 ISO
power("reset") # 重启到安装程序
# 截图 → 点击 → 输入文本 … 人工智能通过视觉浏览安装程序
unmount_media()
```
设备的存储分区很小，因此 `mount_media_url` （设备通过 HTTP 流式传输镜像，
带有范围请求）是完整大小 ISO 的正确路径；`upload_and_mount` 用于小型恢复镜像。
## 注意事项（在报告错误之前请阅读）
- **第一张截图需要 ~3 秒；其余的都是瞬间的。** 设备仅在通过 RTCP PLI 请求时才会发出 H.264 关键帧。浏览器会自动请求关键帧；aiortc 不会 —
因此客户端在连接时和帧过期时发送 PLI（`_request_keyframe` 在
`client.py` 中）。如果没有，解码将永远失败
（`avcodec_send_packet: Invalid data`）。如果您正在构建自己的客户端：这是陷阱。
- **键盘布局**：`type_text` 映射 ASCII → USB HID 使用代码，假设目标 OS 上的 **US 布局**。
在其他布局中，移位符号交换（在 UK 目标上，`"` 到达时为
`@`）。字母，数字和 `/ - . ; =` 是布局稳定的；请在关键命令中使用它们。
- **坐标**：`click`/`move_mouse` 获取最近的
`screenshot` 上的像素坐标；客户端使用实时帧
尺寸将它们映射到 HID 绝对范围，因此没有漂移。
- **`getVideoState` 可能会报告 `streaming: 0`** 即使帧以 60 fps 流畅播放 — 只是外观问题，忽略它。
- **TLS**：股票固件在 LAN 上提供纯 HTTP。设备支持可选 TLS
（设置 → 高级）— 启用它并设置 `JETKVM_URL=https://…`，如果证书受信任，则添加
`JETKVM_VERIFY_TLS=true`。WebRTC 媒体/控制是 DTLS/SRTP-encrypted
对等方之间，无论信令如何。
- **`power` 需要 ATX 扩展板** 连接到主板头部；如果没有，它就是一个无效操作（`power_state` 读取 `power: false`）。
## 安全
这允许语言模型驱动具有真实后果的真实计算机。建议：
- 首先将其指向测试盒或实验室机器，而不是生产 NAS。
- 破坏性工具是 `power`，`reboot_device`，`dc_power`，`mount_*`，
`delete_storage_file` 和任何重启组合的 `press_key` — 考虑在您的 MCP 客户端的权限设置中需要每次调用确认。
- 如果 JetKVM 只能由您访问，请设置设备密码（和 TLS）。
## 开发
```
jetkvm/client.py WebRTC + JSON-RPC 客户端（连接，截图，HID 输入，上传）
jetkvm/keymap.py ASCII / 键组合 → USB HID 使用代码
server.py FastMCP 服务器，暴露 24 种工具
smoke_test.py 针对真实设备的实时端到端检查
docs/ 架构 + 工具参考
```
在固件/应用程序 **0.5.8** （2026 年 7 月）上针对 JetKVM v2 验证端到端：持续
60 fps 解码，键盘输入，HTTP CDROM 挂载/卸载，ATX/DC 状态读取 — 包括从实时克劳德会话驱动。
RPC 表面已针对
[jetkvm/kvm](https://github.com/jetkvm/kvm) 源代码进行验证。
### 想法 / 路线图
- `type_text` 的键盘布局配置文件（当前为硬编码的 US）
- 在环境标志后禁用破坏性工具
- 原生 `getSnapshot` RPC 在固件中将删除对 H.264 解码的依赖
（参见 jetkvm/kvm#1459）
## 许可证
[MIT](LICENSE)。与 JetKVM/Improve Robotics 无关 — 这是该设备的公共 API 的独立客户端。
