Vibe Console MCP

MCP（模型上下文协议）服务器，用于通过noVNC控制Proxmox VM。它允许AI代理通过Proxmox API和noVNC websocket与VM控制台（包括早期启动阶段）交互。

\[！注意\] VibeConsole MCP当前处于 测试版.

\[！注意\] 目前，最佳的使用方式是串行方式。带有OCR选项的noVNC需要更多的细化，并且计算量更大。

termproxy预览

termproxy preview

noVNC预览

preview

特性

• 控制台访问：通过Proxmox API通过noVNC连接到VM控制台
• 串行控制台访问：连接到VM串行控制台（xterm.js后端）进行原始文本I/O
• AI代理控制：发送键盘输入并捕获真实的JPEG/PNG屏幕截图
• 网格叠加系统：在屏幕截图中添加坐标网格以提高空间感知能力
• 增强型OCR：获取具有精确边界框和网格单元格位置的文本
• 基于网格的点击：单击网格参考（例如“K9”）而不是像素坐标
• 开机监控：等待启动阶段并检测系统状态
• VM控制：直接从代理启动、停止、重新启动VM
• 无需VM安装：完全通过Proxmox工作，虚拟机上不需要代理
• 基于图像的屏幕截图：使用Sharp库进行正确的RFB协议解析，以获得高质量的屏幕截图

支持的工具

需求

• Node.js 20+
• Proxmox VE 8.0+
• 具有的Proxmox用户或API令牌 VM.Console, VM.Audit 和 VM.PowerMgmt 权限
• 对Proxmox API（默认端口）的网络访问 8006)

安装

1. 克隆存储库并输入目录：

git clone https://github.com/Andreansx/VibeConsole-MCP.git
cd VibeConsole-MCP

1. 安装依赖项（使用 npm ci 在CI环境中）：

npm install

1. 构建TypeScript输出：

npm run build

1. 在开发（观察）模式下运行：

npm run dev

1. 启动内置服务器：

npm start

配置

复制 .env.example 到 .env 并为您的环境更新值：

cp .env.example .env

所需的环境变量

可选/OCR设置

可选/串行设置

Proxmox设置（推荐）

1. 创建专用用户（如果使用令牌，则可选）：

pveum user add vibeconsole@pve --password 'your_password'

1. 创建具有所需权限的角色：

pveum role add VibeConsole --privs "VM.Console VM.Audit VM.PowerMgmt"

1. 向用户授予群集、节点和VM的权限：

pveum acl modify / --users vibeconsole@pve --role VibeConsole
pveum acl modify /nodes/pve --users vibeconsole@pve --role VibeConsole
pveum acl modify /vms/108 --users vibeconsole@pve --role VibeConsole

1. 创建API令牌（首选于无人参与的服务器）：

pveum user token add vibeconsole@pve mcp-token --privsep 0
# Save the token secret from the command output and place it into .env

1. （可选）如果需要，直接向令牌授予ACL：

pveum acl modify / --tokens vibeconsole@pve!mcp-token --role VibeConsole

1. （可选）启用串行控制台以访问xterm.js（串行工具需要）：

• 添加硬件→ 串行端口→ 串行0（插座）
• 设置选项→ 控制台→ xterm.js（serial 0）
• 确保客户操作系统启用串行控制台（例如，Linux内核arg console=ttyS0,115200n8 然后穿上 ttyS0)
• 串行访问使用Proxmox termproxy端点；如果失败，请验证VM是否具有serial0，以及您的用户/令牌是否具有VM。慰问。

串行快速设置（主机+客户机）

运行这些帮助程序以启用端到端串行控制台：

在Proxmox主机上：

./scripts/enable-serial-host.sh 

或者通过curl：

curl -fsSL https://raw.githubusercontent.com/Andreansx/VibeConsole-MCP/main/scripts/enable-serial-host.sh | bash -s -- 

在虚拟机（Linux/systemd）内部：

./scripts/enable-serial-guest.sh
sudo reboot

或者通过curl：

curl -fsSL https://raw.githubusercontent.com/Andreansx/VibeConsole-MCP/main/scripts/enable-serial-guest.sh | bash
sudo reboot

笔记：

• 主机脚本设置 serial0 （插座）和 vga=serial0.
• 来宾脚本添加内核参数并启用 serial-getty@ttyS0.
• 如果您的客户机使用非GRUB引导加载程序，请手动更新内核参数。
• 为了安全起见，请在连接到bash之前查看脚本内容。

用法

作为MCP服务器（用于AI代理）

该项目发布 dist/index.js 建成后。典型的MCP客户端（Claude、Cursor等）可以通过运行 node 指向内置入口点的命令，或使用提供的 vibeconsole-mcp 如果安装了垃圾箱。

示例配置（替换路径和机密）：

{
  "mcpServers": {
    "vibeconsole": {
      "command": "node",
      "args": ["/path/to/VibeConsole-MCP/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "pve",
        "PROXMOX_PORT": "8006",
        "PROXMOX_TOKEN": "vibeconsole@pve!mcp-token",
        "PROXMOX_SECRET": "your-token-secret",
        "DEFAULT_NODE": "pve",
        "DEFAULT_VMID": "108"
      }
    }
  }
}

用于游标IDE

Cursor和其他集成了IDE的MCP客户端可以类似地配置——指向 dist/index.js 入口点，并根据需要提供环境变量。

测试

构建后运行项目的测试脚本：

npm run build
npm test
npm run test:image
npm run test:sharp

示例用法

以下是AI代理可能使用的示例工作流：

// 1. Connect to VM console
await mcp.callTool('connect_to_vm', { vmid: 108, node: 'pve' });

// 2. Wait for screen to stabilize
await new Promise(resolve => setTimeout(resolve, 3000));

// 3. Capture screen as JPEG
const screenshot = await mcp.callTool('read_screen', {
  format: 'jpeg',
  quality: 85
});
// Returns base64-encoded JPEG image

// 4. Send keyboard input
await mcp.callTool('send_keys', {
  keys: ['Enter', 'user', 'Enter', 'password', 'Enter']
});

// 5. Capture another screenshot
const newScreenshot = await mcp.callTool('read_screen', {
  format: 'png'
});

\[！提示\] 使用串行控制台工具时，请在以下位置立即发送换行符 connect_to_serial 在第一次之前 read_serial 或 read_screen 电话。这会唤醒登录提示，使初始读取不为空。

网格叠加示例

使用网格覆盖进行精确的GUI交互：

// 1. Capture screen with grid overlay
const screen = await mcp.callTool('read_screen', {
  overlay: 'grid',
  gridSize: 50,
  format: 'png'
});
// Vision model sees grid and identifies "Next" button at K9

// 2. Click at the identified grid cell
await mcp.callTool('click_grid', {
  cell: 'K9',
  button: 'left',
  gridSize: 50
});

// 3. Or click by OCR text
await mcp.callTool('click_text', {
  text: 'Next',
  matchMode: 'exact',
  clickType: 'single'
});

// 4. Or find text with regex and then decide where to click
const matches = await mcp.callTool('find_text', {
  query: 'next|continue',
  matchMode: 'regex',
  caseSensitive: false
});

// 5. Or use enhanced OCR to find elements
const ocrResult = await mcp.callTool('read_screen', {
  ocr: true,
  includeElementBounds: true,
  overlay: 'grid'
});
// Returns text with bounding boxes and grid cells

看 网格叠加指南 详细文档。

运作原理

1. 认证：对REST调用使用Proxmox API令牌，对WebSocket使用PVEAuthCookie
2. VNC代理：通过创建临时VNC会话 /vncproxy 端点
3. 双向通信：连接到 /vncwebsocket 通过适当的身份验证
4. 屏幕截图：接收VNC帧并将其作为屏幕截图提供
5. 输入：发送VNC键事件以进行键盘控制

建筑

AI Agent (Claude/Cursor)
    ↓ MCP Protocol
VibeConsole-MCP Server (Node.js)
    ├── Proxmox API Client (REST: HTTP/HTTPS:8006)
    │   └── Auth: API Token + Cookie
    └── VNC WebSocket (WSS:8006)
        └── noVNC proxy on Proxmox
            └── VM Console (QEMU/KVM)

SSL/TLS注意事项

Proxmox API使用自签名证书。发展：

• MCP服务器自动信任Proxmox CA证书
• 对于生产环境，请在系统的信任存储中安装Proxmox CA证书

要从Proxmox获取CA证书，请执行以下操作：

ssh root@pve 'cat /etc/pve/pve-root-ca.pem'

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type checking
npm run typecheck

局限性

• 一些高级指针功能（绝对指针/抓取）可能会受到限制，具体取决于访客和noVNC行为；通过支持基本指针事件 send_mouse 工具。
• WebSocket连接需要正确的SSL处理才能实现安全的Proxmox设置
• 屏幕捕获质量取决于VM帧缓冲区大小和网络速度
• 默认帧缓冲区大小为1024x768（可在RFB解析器中调整）

路线图

• \[x\] 添加适当的图像编码（PNG/JPEG截图）
• \[X\] 添加鼠标支持
• \[X\] 添加OCR用于屏幕上的文本检测
• \[\]同时支持多个VM连接
• \[\]添加启动日志捕获
• \[\]实现自适应帧缓冲区大小检测

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

• 代码遵循现有的TypeScript风格
• 所有测试均通过(npm test)
• 类型检查通过(npm run typecheck)

故障排除

401 WebSocket未经授权

这通常表示VNC票证存在身份验证问题。验证您是否传递了正确的API令牌/机密，或者Proxmox REST API是否正确生成了基于ticket的身份验证。

拒绝许可（403）

确保用户或令牌具有所需的ACL和对目标VM的访问权限：

• 确认分配的角色包括 VM.Console, VM.Audit，以及 VM.PowerMgmt
• 确认ACL已应用于令牌/用户需要访问的群集/节点/VM路径

SSL/证书错误

如果MCP服务器引发证书验证错误：

• 在运行MCP服务器的主机上安装Proxmox CA证书
• 仅用于开发，您可以设置 NODE_TLS_REJECT_UNAUTHORIZED=0，但不要在生产中使用它

要从服务器导出Proxmox CA证书，请执行以下操作：

ssh root@pve 'cat /etc/pve/pve-root-ca.pem'

OCR返回的结果很差

如果OCR输出质量低或显示垃圾字符：

• 确保服务器正在运行最新版本(npm run build)并重新启动MCP服务器，以便使用更新的代码
• 增加 OCR_WORKERS 或者在内存/CPU允许的情况下调整图块大小
• 通过增加VM帧缓冲区或使用更高的捕获分辨率来提高捕获质量

如果 npm run test:ocr 成功，但正在运行的MCP服务器仍然显示OCR错误，正在运行的进程可能是旧版本——重建并重新启动进程。

致谢

• 内置于 模型上下文协议
• 由...驱动 Proxmox VE
• Proxmox的noVNC技术