Metadata-Version: 2.5
Name: kvmcp
Version: 1.0.0
Summary: MCP server for video capture and USB HID control
Author-email: sjtu_6547 <88172828@qq.com>
License-File: LICENSE
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 大模型的专用工作流。

## 开发板选型

> ⚠️ 短板 ⭐ 优势 ✅ 已实测 ❓ 未实测 

| 项目 | [Raspberry Pi Zero 2 W](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/) | [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) |
|---|---|---|---|
| 参考价格 | 899 元 | 415 元 | 299 元 |
| 处理器 | 4× Cortex-A53，1 GHz | 4× Cortex-A53，最高 1.5 GHz | 4× Cortex-A55，最高 1.6 GHz |
| 内存 | ⚠️ 512 MB LPDDR2 | 2 GB LPDDR4 | 2 GB LPDDR4 |
| 无线网络 | ⚠️ 2.4 GHz Wi-Fi 4、蓝牙 4.2 | Wi-Fi 5、蓝牙 5.0 | Wi-Fi 6、蓝牙 5.4 |
| 独立 USB Host | ⚠️ 无 | USB1：USB 2.0 Type-C | USB 3.0 Type-C ⭐ |
| USB Device | Micro-USB OTG，HID Gadget | USB0：USB 2.0 Type-C，HID Gadget ✅ | USB 2.0 Type-C OTG，HID Gadget ❓ |
| HID 兼供电 | 支持 | 稳定支持 ✅ | 稳定支持 ❓ |
| 存储 | microSD | microSD | microSD + eMMC |
| 视频输出 | Mini HDMI | Mini HDMI | Micro HDMI |
| 扩展接口 | 40-pin GPIO | 40-pin GPIO + 24-pin 专用扩展板 | 40-pin GPIO + MIPI CSI |
| 尺寸 | 65 × 30 mm | 65 × 30 mm | 65 × 30 mm |

## 安装与运行

#### 安装系统依赖

```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-hid kvmcp
```

#### 升级

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

#### 接入 Codex（可选）

在可访问 kvmcp 设备的电脑上，将 `KVMCP_IP` 换成该设备的地址：

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

## Q&A

#### kvmcp 支持哪些 Agent

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

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

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