内容
# GLKVM MCP 服务器
一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，暴露了 [GL.iNet GLKVM](https://www.gl-inet.com/products/gl-sg24/) / PiKVM 分支设备的键盘、鼠标和 **OCR 增强截图** 功能，作为 AI 代理工具。
通过 IP-KVM 控制远程机器 — 输入、点击、截图和 **读取屏幕文本** — 所有操作都通过结构化的 MCP 工具调用，任何 LLM 代理（Claude、GPT、GLM 等）可以直接使用。
## ✨ 主要功能
- **完整的键盘控制** — 输入文本、发送按键组合（Ctrl+Alt+Del、Win+L、F11）、按住按键
- **精确的鼠标控制** — 移动、点击、滚动，基于百分比定位（100% 精确）
- **截图捕获** — 全分辨率或预览，作为 MCP 图片内容返回
- **🔧 OCR 增强定位** — 内置 Tesseract OCR 集成：
- 读取远程屏幕上的所有文本，带有精确的像素和百分比坐标
- 让代理可以通过 **文本名称** 点击 UI 元素，而不是猜测坐标
- 消除了不可靠的“视觉模型估计像素位置”模式
## 🎯 为什么需要 OCR 集成？
视觉模型（GPT-4V、Claude Vision、GLM-4V）在 *读取* 截图方面表现良好，但在 *估计像素坐标* 方面表现不佳 — 通常偏差超过 30%。而 KVM 鼠标的准确度小于 0.5%。瓶颈始终是 **知道在哪里点击**，而不是点击本身。
**之前（不可靠）：**
```
代理：“‘Day’ 按钮在哪里？”→ 视觉模型：“大约 45%，15%”→ 未命中
```
**之后（OCR 增强）：**
```
代理：kvm_ocr_click("Day") → OCR 查找精确位置 → 点击正中心 → ✅
```
## 📦 安装
### 1. 安装 Tesseract OCR（系统依赖）
```bash
# Windows
choco install tesseract-ocr
# 或从 https://github.com/UB-Mannheim/tesseract/wiki 下载
# macOS
brew install tesseract
# Linux（Debian/Ubuntu）
sudo apt-get install tesseract-ocr
```
### 2. 在您的 MCP 客户端中配置
将以下内容添加到您的 MCP 客户端配置文件中（例如，Claude Desktop `claude_desktop_config.json`，Hermes `config.yaml`）：
```json
{
"mcpServers": {
"glkvm": {
"command": "uv",
"args": [
"run",
"--script",
"/path/to/glkvm_mcp.py"
]
}
}
}
```
Python 依赖项（`mcp`、`websockets`、`httpx`、`Pillow`、`pytesseract`）通过内联 PEP 723 元数据由 `uv run --script` 自动安装。
## 🔧 工具
### 连接
| 工具 | 描述 |
|------|-------------|
| `kvm_connect(host, password, username?)` | 连接到 LAN 上的 GLKVM 设备 |
| `kvm_disconnect()` | 关闭会话 |
| `kvm_status()` | 报告连接状态和按住的按键 |
### 键盘
| 工具 | 描述 |
|------|-------------|
| `kvm_send_text(text, wpm?)` | 输入字符串（原子按键模式修复卡住按键错误） |
| `kvm_send_keys(combo)` | 发送按键组合（例如，“Ctrl+Alt+Delete”、“F5”、“Win+L”） |
| `kvm_hold_key(key, duration_ms)` | 按住按键（用于自动重复滚动） |
| `kvm_release_all()` | 强制释放所有按住的按键 |
### 鼠标
| 工具 | 描述 |
|------|-------------|
| `kvm_mouse_move(x, y)` | 移动到绝对 int16 坐标 |
| `kvm_mouse_move_pct(x_pct, y_pct)` | 移动到屏幕百分比（0,0 = 左上角） |
| `kvm_mouse_click(button?, count?)` | 在当前位置点击 |
| `kvm_mouse_scroll(dx?, dy?)` | 滚动鼠标滚轮 |
### 截图
| 工具 | 描述 |
|------|-------------|
| `kvm_screenshot(preview?, max_width?, quality?)` | 捕获 JPEG 帧作为 MCP 图片内容 |
| `kvm_screenshot_to_file(path, preview?, ...)` | 捕获并保存到磁盘 |
### 🔧 OCR 增强（Tesseract）
| 工具 | 描述 |
|------|-------------|
| `kvm_ocr_screenshot(search_text?, preview?)` | 捕获 + OCR：返回所有文本和坐标 |
| `kvm_ocr_click(text, button?, count?, search_area?)` | 通过 OCR 查找文本并点击 — 一步到位 |
## 📖 使用示例
### 通过文本名称点击按钮
```python
# 一步操作：截图 → OCR → 查找“Save”→ 移动鼠标 → 点击
kvm_ocr_click("Save")
```
### 读取屏幕上的所有文本
```python
# 返回带有每个检测到的单词和坐标的结构化 JSON
result = kvm_ocr_screenshot()
# {"width": 1920, "height": 1080, "elements": [
# {"text": "File", "confidence": 96.3, "x_pct": 5.2, "y_pct": 3.1, ...},
# {"text": "Edit", "confidence": 95.8, "x_pct": 8.7, "y_pct": 3.1, ...},
# ...
# ]}
```
### 查找特定文本并获取其坐标
```python
result = kvm_ocr_screenshot("Submit")
# {"elements": [{"text": "Submit", "confidence": 94.5, "x_pct": 52.3, "y_pct": 87.1, ...}]}
# 然后使用：kvm_mouse_move_pct(52.3, 87.1) + kvm_mouse_click()
```
### 用搜索区域消除歧义
```python
# 如果“OK”出现在多个位置，限制在右下角
kvm_ocr_click("OK", search_area="bottom-right")
```
### 传统截图（用于视觉模型分析）
```python
# 返回 MCP 图片内容 — 代理直接看到截图
kvm_screenshot(preview=True, max_width=1024)
```
## 🏗️ 架构
```
┌──────────────┐ MCP 标准输入输出 ┌─────────────────┐ HTTPS/WSS ┌──────────┐
│ AI 代理 │ ◄─────────────────► │ glkvm_mcp.py │ ◄───────────────► │ GLKVM │
│ （Claude/GPT）│ 工具调用 │ （此服务器） │ （PiKVM API） │ 设备 │
└──────────────┘ └─────────────────┘ └──────────┘
│
Tesseract OCR
（读取截图文本）
```
服务器与 GLKVM 设备保持持久的 WebSocket 连接，以实现低延迟的键盘/鼠标输入，并使用 HTTP 进行截图和身份验证。
## 🔒 安全
- **仅限局域网** — 设计用于受信任的本地网络
- **禁用 TLS 验证** — 设备自带自签名证书
- **无凭证存储** — 密码通过工具调用逐次传递
## 🐛 已实施的错误修复
此服务器包含已知 GLKVM/PiKVM 固件错误的修复：
- **卡住按键 / 双重输入** （固件 ≤ 1.9.0）：每个字符作为原子按键按下 → 25ms → keyup（finish=true）
- **修饰符释放顺序错误** （gl-inet/glkvm #22）：修饰符严格包装在主按键之外
- **过时按键看门狗**：自动释放任何按键超过 250ms
## 📋 要求
- Python ≥ 3.10
- 一个 GL.iNet GLKVM 设备（固件 1.9.0+）或您的局域网上的 PiKVM 兼容设备
- 主机上安装 Tesseract OCR
## License
MIT
