cvm-vnc 0.1.9

Tencent Cloud CVM VNC browser control via agent-browser with MCP server support

cvm-vnc

通过 agent-browser 对 Web VNC 页面进行程序化控制的 Python 工具，支持屏幕截图、文本输入和页面状态检测，并提供 MCP (Model Context Protocol) Server 供 AI Agent 集成。

功能特性

• VNC 页面控制 — 打开并操作 Web VNC 界面
• 屏幕截图 — 将 VNC Canvas 捕获为 PNG 图片
• 智能文本输入 — 自动识别输入方式（远程命令对话框 / noVNC 键盘 / Canvas 直接输入等）
• MCP Server — 以 stdio 模式运行，供 AI Agent 调用
• 登录检测 — 自动识别 VNC 页面跳转至登录页的场景
• 终端网格估算 — 根据 Canvas 尺寸启发式推算终端行列数

安装

从源码安装（开发模式）

git clone <repo-url>
cd cvm-vnc
pip install -e .

-e（editable）模式会将当前源码目录链接为已安装包，修改代码后无需重新安装即可生效。

从 PyPI 安装

pip install cvm-vnc

可选依赖

# dotenv 支持（从 .env 文件加载环境变量）
pip install -e '.[dotenv]'

前置依赖

需要系统中安装 agent-browser（Node.js CLI 工具）：

npm install -g agent-browser

使用方式

CLI 命令

# 打开 VNC 页面
cvm-vnc open <url> [--wait-ms MS] [--session NAME] [--headed]

# 截取 VNC 屏幕
cvm-vnc capture [output] [--session NAME] [--headed]

# 发送文本输入
cvm-vnc type <text> [--enter] [--session NAME] [--headed]

# 批量顺序输入（避免 AI 思考间隙导致登录超时）
cvm-vnc type-sequence --steps-json '<JSON>' [--mode MODE] [--session NAME]

# 关闭浏览器会话
cvm-vnc close [--session NAME]

# 启动 MCP Server
cvm-vnc mcp [--session-default NAME] [--mode-default MODE] [--headed]

也可通过独立入口直接启动 MCP Server：

cvm-vnc-mcp

MCP Server Tools

MCP Server 对外暴露以下工具：

工具	说明
vnc_open(url, wait_ms, session)	打开 VNC 页面
vnc_status(session)	检查页面状态（Canvas 元数据、登录检测等）
vnc_capture(output_path, session)	截取 Canvas 为 PNG
vnc_type(text, press_enter, session, mode)	发送文本输入
vnc_type_sequence(steps, session, mode)	批量顺序输入（适合系统登录等需要连续输入的场景）
vnc_close(session)	关闭浏览器会话，释放资源

示例

# 打开 VNC 并等待页面加载
cvm-vnc open https://vnc.example.com --wait-ms 3000

# 截图保存到文件
cvm-vnc capture /tmp/screen.png

# 执行命令
cvm-vnc type "ls -la" --enter

# 一次性完成系统登录（用户名 + 密码）
cvm-vnc type-sequence --steps-json '[{"text":"root","press_enter":true,"wait_ms":500},{"text":"password","press_enter":true}]'

# 关闭浏览器会话
cvm-vnc close

项目结构

src/cvm_vnc/
├── __init__.py        # 版本信息
├── __main__.py        # CLI 入口
└── vnc_browser.py     # 核心实现（浏览器控制、MCP Server、JS 注入脚本）

MCP Server 配置

安装完成后，可将 cvm-vnc 作为 MCP Server 接入 AI 客户端。

Claude Code

claude mcp add cvm-vnc -- cvm-vnc-mcp

添加后可通过以下命令验证：

claude mcp list

Codebuddy

codebuddy mcp add cvm-vnc -- cvm-vnc-mcp

或手动编辑 ~/.codebuddy/settings.json：

{
  "mcpServers": {
    "cvm-vnc": {
      "command": "cvm-vnc-mcp"
    }
  }
}

提示：如果 cvm-vnc-mcp 不在 PATH 中，需使用完整路径，例如 /path/to/venv/bin/cvm-vnc-mcp。

配置

环境变量	说明	默认值
AGENT_BROWSER_BIN	agent-browser 可执行文件路径	自动查找
LOCK_TIMEOUT	会话锁超时时间（秒）	120

License

MIT