内容
Agentic-KVM
MCP 服务器通过 PiKVM 为 AI 代理提供远程机器的裸金属控制。**
> **状态：** v0基础版本。这是商业设备和云托管计算机即服务产品的开源核心。
> 它测试，但功能尚未完整。欢迎贡献。
## 功能Agentic-KVM 将 PiKVM 的 REST API 暴露工具，任何 AI 代理都可以调用：
- **MSD** （大容量存储设备）— 上传 ISO，挂载虚拟驱动器，从安装程序启动
- **ATX** — 通过主板表头引脚开机、关机、硬重置
- **HID** — 键盘、鼠标、截图和基于截图的鼠标校准
- **审计追踪** — 每个工具调用都记录到 JSONL 中，以确保责任链的完整性
## 架构
```
┌──────────────┐ stdio/MCP ┌──────────────────┐ HTTPS ┌─────────┐
│ AI 代理 │◄──────────────────►│ Agentic-KVM │◄───────────►│ PiKVM │
│ （Claude、 │ │ （FastMCP 服务器） │ Tailscale │ 设备 │
│ 等） │ │ │ │ │
└──────────────┘ └──────────────────┘ └─────────┘
│
▼
/var/log/pikvm-mcp/
session-<id>.jsonl
```
PiKVM 客户端位于 `TargetBackend` 抽象后面。未来的后端（Redfish BMC、Azure VM、RDP）将实现相同的接口，因此工具层不会改变。
## 快速入门
### 前提条件
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) 用于环境管理
- 一个可以通过网络访问的 PiKVM 设备（推荐使用 Tailscale）
### 本地安装和运行
```bash
uv sync
export PIKVM_TARGETS='[{"name":"my-kvm","host":"pikvm.ts.net","password":"your-password"}]'
export PIKVM_OPERATOR_ID="your-name"
uv run pikvm-mcp
```
### Docker（生产环境推荐）
```bash
docker build -t pikvm-mcp .
docker run -d --name pikvm-mcp \
-e PIKVM_TARGETS='[{"name":"lab","host":"pikvm-lab.ts.net","password":"..."}]' \
-e PIKVM_OPERATOR_ID=operator@redteam \
-v pikvm-mcp-audit:/var/log/pikvm-mcp \
pikvm-mcp
# 连接 MCP 客户端
docker exec -i pikvm-mcp pikvm-mcp
```
### Claude Desktop / MCP 客户端配置
```json
{
"mcpServers": {
"pikvm": {
"command": "docker",
"args": ["exec", "-i", "pikvm-mcp", "pikvm-mcp"]
}
}
}
```
### 本地 MCP 客户端配置
对于本地测试，在忽略的 `.env` 文件中保留密钥，并使用 `PIKVM_ENV_FILE` 指向该文件。这样可以避免在客户端配置文件中复制 PiKVM 密码。
```json
{
"mcpServers": {
"agentic-kvm": {
"command": "uv",
"args": [
"--directory",
"/path/to/Agentic-KVM",
"run",
"python",
"-m",
"pikvm_mcp.server"
],
"env": {
"PYTHONPATH": "/path/to/Agentic-KVM/src",
"PIKVM_ENV_FILE": "/path/to/Agentic-KVM/.env"
}
}
}
}
```
将 `/path/to/Agentic-KVM` 替换为本地代码库路径。
生产环境部署应继续通过容器、进程监视器或密钥管理器直接传递真正的环境变量。
## 多目标配置
Agentic-KVM 从一开始就支持多个 PiKVM 目标。每个工具都接受一个可选的 `target` 参数。
```bash
export PIKVM_TARGETS='[
{"name": "lab-server", "host": "pikvm-lab.ts.net", "password": "..."},
{"name": "prod-server", "host": "pikvm-prod.ts.net", "password": "...", "port": 8443}
]'
export PIKVM_DEFAULT_TARGET=lab-server
```
| 环境变量 | 描述 | 默认值 |
|-----------|-------------|---------|
| `PIKVM_TARGETS` | 目标配置的 JSON 数组 | `[]` |
| `PIKVM_DEFAULT_TARGET` | 默认目标名称 | 列表中的第一个 |
| `PIKVM_OPERATOR_ID` | 审计日志的操作员 ID | `unknown` |
| `PIKVM_AUDIT_DIR` | JSONL 审计日志的目录 | `/var/log/pikvm-mcp` `PIKVM_FULL_CAPTURE` | 在审计日志中包含操作员输入的 HID 文本 | `false` |
### 目标配置字段
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `name` | 字符串 | 必需 | 人类可读的标识符 |
| `host` | 字符串 | 必需 | 主机名或使用 Tailscale MagicDNS） |
| ` | 整数 | `443` | HTTPS 端口 |
` | 字符串 | `admin` | PiKVM 用户名 |
| `password` | 字符串 | `admin` | PiKVM 密码 |
| `otp_secret` | 字符串 | `null` | 2FA 的 TOTP 密钥 |
| `verify_ssl` | 布尔值 | `false` | 验证 TLS 证书 |
| `cert_fingerprint` | 字符串 | `null` | 证书固定的 SHA-256 指纹 |
## Tailscale 设置
推荐的部署方式是将 PiKVM 放在 Tailnet 上：
1. 在 PiKVM 上安装 Tailscale：https://docs.pikvm.org/tailscale/
2. PiKVM 获得一个类似 `pikvm-lab.ts.net` 的 MagicDNS 名称
3. 设置 `verify_ssl: false`（PiKVM 使用自签名证书）
4. 对于高安全性部署，获取证书指cert_fingerprint`
自签名 SSL 是 PiK常态。`verify_ssl: false` 默认值是故意的，而不是懒惰的。
当设置了 `cert_fingerprint` 时，Agentic-KVM 首先打开一个未经身份验证的 TLS 连接来验证 PiKVM 证书指纹。只有在预检成功后，它才会创建经过身份验证的 HTTP 客户端，使用一个仅将固定的证书作为其唯一信任根的 SSL 上下文。这样可以防止在呈现的证书与符时，将 PiKVM 凭证传递到线路上。
## 审计日志
每个工具调用都会记录在 `/var/log/pikvm-mcp/session-<id>.jsonl` 中：
```json
{
"ts": "202-15T12:34:56.789Zsession_id": "a1b2c4",
"target "lab-server",
operator_id": "operator@redteam",
"tool": "pikvm_atx_power " {"target": "lab-server"},
"result": " "duration_ms": 342
}
```
密码牌、OTP 密钥和内部客户端对象会自动从记录的参数中删除。
默认情况下，输入的 HID 文本会被编辑以隐藏敏感信息，因为它可能包含密码、恢复密钥、BIOS 字段或包含密钥的命令：
```json
{"tool": "type_text", "args": {"target-server", "text": "***"}}
```
对于明确，设置 `PIKVM_FULL_CAPTURE=true完全捕获日志会记录 HID 文本，但仍然会编辑类似凭证的字段，如密码、令牌和。只有在操作员范围允许敏感输入捕获时才启用它。
## 开发
```bash
uv sync
uv run pytest
uvuff check src/ tests/
```
### PiKVM 集成测试
集成测试默认跳过。它们会从 `.env` 加载 PiKVM 设置，然后覆盖任何 `PIKVM_*` 进程环境变量。
只读集成测试：
```bash
PIKVM_INTEGRATION=1 uv run pytest tests/integration integration
```
H，例如移动鼠标，需要的确认：
```bash
PIKVM_IN=1 PIKVM_ALLOW_HID_ACTIONS=1 \
uv run pytest tests/integration -m "integration and hid_action"
```
未来的 MSD 和 ATX 操作测试应使用相同的模式：
`PIK_MSD_ACTIONS= 和 `PIKVM_ALLOW_ATX_ACTIONS=。MSD 操作测试期望 PiKVM 存储中存在一个现有的镜像，默认为
`PIKVM_TEST=netboot.xyz.iso`。
```bash
PIKVM_INTEGRATION=1 PIKVM_ALLOW_MSD_ACTIONS=1 \
uv run pytest tests/integration -m "integration and msd_action"
```
即使在实验室硬件上，也要保持破坏性或改变状态的测试为可选。
ATX 操作测试需要通用 ATX 确认和特定操作：
```bash
PIKTEGRATION=IKVM_ALLOW_ATX=1 \
VM_TEST_ATX_ACTION_on \
uv run pytest tests/integration -m "integration and atx_action"
```
仅当目标的 PiKVM ATX 表头布 LED 状态被认为可靠时，才使用 ATX 操作。
用工具
### MSD（大容量存储设备 `pikvm_msd_state` — 当前- `pikvm_msd_upload_url` — 下载 ISO 到 MSD- `piksd_set_image` — 选择镜像和模式（CD-ROM存）
-ikvm_msd — 将虚拟驱动器- `pikvm_msd_disconnect` — 断开虚拟驱动器
### ATX（电源控制 `pikvm_atx_state` — 电源 LED，HDD LED `pikvm_power_on` —电源按钮
-ikvm_atx_power_off` — 长按电源按钮
- `pikvm_atx_power_off_hard 5 秒按住pikvm` — 脉按钮
### HID/鼠标）
- `vm_hid_state HID 子系统状态 `pikvm_s — 捕获 JPEG并检测分辨率
pikvm_hid — 输入文本字符串
- `pikvm_hid` — 按下/释放按键；一次性按键释放
- `vm_hid_short下多键
- `pikvm_mouse_move` —或原始 PiKVM坐标移动光标 `pikvm — 在当前或标位置单击
pikvm_mouse_scroll` — 滚轮- `pikvm_hid_calibrate` — 刷新基于截图的鼠标校准
## 依赖强化计划
dogfood MVP 具有广泛的依赖范围和已检查的 `uv.lock`，用于可复制的本地安装。在生产强化之前，项目应转向固定的运行时依赖、固定的 Docker 基础/工具镜像和 30 天的依赖老化规则：新发布的依赖版本不得进入生产镜像，直到老化至少 30 天，除非安全修复需要明确。
生产强化目标连接的对证书强制在传输中执行，因此在发送经过身份验证的请求数据之前直接新的 TLS 连接。
## 许可证
MIT
