Metadata-Version: 2.5
Name: kvmcp
Version: 1.1.0
Summary: MCP server for video capture, USB HID control and USB extensions
Project-URL: Homepage, https://github.com/doidio/kvmcp
Project-URL: Source, https://github.com/doidio/kvmcp
Project-URL: Issues, https://github.com/doidio/kvmcp/issues
Author-email: sjtu_6547 <88172828@qq.com>
License-Expression: MIT
License-File: LICENSE
Keywords: computer-use,kvm,mcp,tcp-forwarding,usb-gadget,usb-hid,video-capture
Requires-Python: >=3.13
Requires-Dist: mcp>=2.2.0
Requires-Dist: tomlkit>=0.15.1
Description-Content-Type: text/markdown

# kvmcp

帮助老旧内网电脑接入 Computer Use Agent 自动化工作流，仅依赖显示器和键鼠接口，无需额外端口开放或权限升级，在此基础上编排面向 VLM 大模型的专用工作流。面向存量信息化系统，减少重复建设与资源浪费，提供边缘 AI 优先的辅助人机交互自动化基础设施。

## 开发板选型

⭐ 优势 ✅ 已实测 ❓ 未实测

| 项目 | [Raspberry Pi 500/500+](https://www.raspberrypi.com/products/raspberry-pi-500/) | [Orange Pi Zero 2W](http://www.orangepi.cn/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-Zero-2W.html) | [Radxa ZERO 3W](https://docs.radxa.com/zero/zero3) |
|---|---|---|---|
| 参考价格 | 1355/3080 元 | 415 元 | 299 元 |
| 处理器 | 4× Cortex-A76，2.4 GHz | 4× Cortex-A53，最高 1.5 GHz | 4× Cortex-A55，最高 1.6 GHz |
| 内存 | 8/16 GB LPDDR4X | 2 GB LPDDR4 | 2 GB LPDDR4 |
| 无线网络 | Wi-Fi 5、蓝牙 5.0 | Wi-Fi 5、蓝牙 5.0 | Wi-Fi 6、蓝牙 5.4 |
| USB Device | USB 2.0 Type-C OTG，HID Gadget ❓ | USB0：USB 2.0 Type-C，HID Gadget ✅ | USB 2.0 Type-C OTG，HID Gadget ❓ |
| HID 兼供电 | 需要 [Type-C 电源信号分离器](https://www.waveshare.net/shop/USB-C-Power-Splitter.htm) | 稳定支持 ✅ | 稳定支持 ❓ |
| 独立 USB Host | 1× USB 2.0 Type-A + 2× USB 3.0 Type-A ⭐ | USB1：USB 2.0 Type-C | USB 3.0 Type-C ⭐ |
| 视频采集 | USB 3.0 采集卡 ⭐ | USB 2.0 采集卡 | USB 3.0 采集卡 ⭐ |
| 双屏采集 | 只需两套采集卡 ⭐ | 需要两套采集卡 + 开发板 | 需要两套采集卡 + 开发板 |
| 视频硬件加速 | H.265 硬解 | H.264 硬编解 H.265 硬解 | H.264/H.265 硬编解 ⭐ |
| 存储 | microSD / microSD + NVMe | microSD | microSD + eMMC |
| 视频输出 | 2× Micro HDMI，双 4K60Hz | Mini HDMI | Micro HDMI |
| 扩展接口 | 40-pin GPIO | 40-pin GPIO + 24-pin 专用扩展板 | 40-pin GPIO + MIPI CSI |
| 外观 | 键盘一体外壳，内置散热 ⭐ | 裸板 | 裸板 |
| 尺寸 | 286 × 122 × 23 mm / 312 × 123.06 × 35.76 mm | 65 × 30 mm | 65 × 30 mm |

**USB 采集与 Wi-Fi 干扰：** USB 3.0 可提供更高的采集带宽，但部分采集卡、接口及线缆可能[干扰 2.4 GHz Wi-Fi](https://www.usb.org/sites/default/files/327216.pdf)，导致连接失败、丢包或断连。若现场仅能使用 2.4 GHz Wi-Fi，且出现此类干扰，应将采集卡改接 USB 2.0，并按带宽调整采集帧率或使用 MJPEG 格式；具备条件时，可改用 5 GHz Wi-Fi 或有线网络，保留 USB 3.0 的采集带宽。

## 安装与运行

#### 安装系统依赖

```sh
sudo apt update
sudo apt install -y ffmpeg v4l-utils
```

#### 安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### 安装 kvmcp

```sh
uv tool install --python 3.13 kvmcp
```

#### 创建配置

```sh
mkdir -p ~/.kvmcp
nano ~/.kvmcp/config.toml
```

配置示例（采集格式和分辨率应按采集设备实际支持情况调整）：

```toml
cache_dir = "/tmp/kvmcp"

[server]
host = "0.0.0.0"
port = 9527

[hid]
text_input = "ascii"

[capture]
input_format = "yuyv422"
video_size = "1920x1080"
framerate = "5"
```

#### 部署系统服务

在 kvmcp 设备上以具备 sudo 权限的普通用户执行：

```sh
# 可选：指定 USB VID/PID
# export KVMCP_USB_VID=0x1d6b
# export KVMCP_USB_PID=0x0104

kvmcp install-service -c ~/.kvmcp/config.toml
systemctl status kvmcp-usb kvmcp
```

#### 升级

```sh
uv tool upgrade kvmcp
kvmcp install-service -c ~/.kvmcp/config.toml
```

## 接入 Codex 使用 computer-use 技能（可选）

启用 computer-use 技能，在可访问 kvmcp 设备的电脑上，将 `KVMCP_IP` 换成该设备的地址：

```sh
codex mcp add kvmcp --url http://KVMCP_IP:9527/mcp
codex mcp list
```

#### 开放限制（此段禁止 Codex 编辑或删除）

如需开放 Windows 命令行等更多操控权限，在每次 Codex 升级变更后，手动移除以下路径 `guidance.md` 文中的 `## Non-negotiable Windows Automation Safety` 整段限制条款和 `## Recovery` 中的锁屏限制条款

```sh
~/.codex/plugins/cache/openai-bundled/computer-use/<变更版本号>/docs/guidance.md
```

## USB 扩展（可选）

| 方式 | 交换形式 | 目标电脑支持要求 |
|---|---|---|
| USB 大容量存储（MSC） | 虚拟磁盘 | USB 存储驱动及读写权限 |
| USB 便携设备（MTP） | 共享目录 | MTP 驱动及便携设备读写权限 |
| USB 以太网（RNDIS） | 网络连接与 TCP 端口转发 | RNDIS 驱动、网络配置及文件服务访问权限 |

通过 TOML 的 `usb.extension` 选择一种扩展，HID 始终保留，其余配置可暂存。USB 以太网内置 TCP 端口转发，可访问服务器已有的 SSH、HTTP 等服务，无需在板端暂存文件。配置与部署见 [USB 扩展说明](https://github.com/doidio/kvmcp/blob/main/deploy/README.md)。

## Q&A

#### kvmcp 支持哪些 Agent

任何能连接 Streamable HTTP MCP、接收图像并调用工具的 Agent 都可以使用 kvmcp

#### 为什么不选用 [PiKVM](https://pikvm.org/)

PiKVM 面向人类远程操作，采用 usteamer 流送视频，确保画面流畅，而 kvmcp 面向 VLM 大模型，采用无损保真的 PNG 截图，确保准确识别画面中的 UI 元素和文字；也不需要独立电源，可用 USB 模拟 HID 兼供电，随目标主机开关

## 更新日志

### 1.1.0 · 2026-10-29

- 统一 USB 扩展配置：通过 `usb.extension` 选择 MSC、MTP 或 RNDIS，始终保留 HID 键盘和鼠标。
- USB 以太网内置 TCP 端口转发，支持多规则、双向流式传输、背压与超时控制，板端无需暂存文件。
- 增加只读运行状态查询；区分 HID 发送与截图结果，避免截图失败导致重复输入。
- 系统服务统一管理 USB 与应用的启动顺序、就绪通知和退出恢复；安装脚本随 PyPI 包提供。
- 完善配置校验、Windows 7 RNDIS 兼容及 USB 切换清理，增加配置、生命周期和并行转发回归测试。
