MCP Server

QVMConsole MCP Server 是 QVMConsole 的 MCP (Model Context Protocol) Server，使 AI 助手能够通过自然语言管理虚拟机。

功能特性

• 查看模板列表 - 浏览所有可用的虚拟机模板
• 创建虚拟机 - 从模板快速创建虚拟机（支持自定义配置）
• 查看虚拟机信息 - 获取详细信息，包括登录密码
• 列出虚拟机 - 查看所有虚拟机及其状态
• 编辑虚拟机 - 修改 CPU、内存等配置
• VNC 操控 - 截图、点击、输入，AI 直接操控虚拟机画面
• 电源管理 - 启动、关机、重启、强制关机等操作
• 快照管理 - 创建、恢复、删除快照
• 磁盘管理 - 添加硬盘、扩容磁盘、查看磁盘列表
• 定时任务 - 创建定时启动、关机等计划任务
• 监控数据 - 获取 CPU、内存、磁盘 I/O、网络流量等实时监控数据

系统要求

• Python 3.10+
• Node.js 16+（使用 npx 方式）
• 一个运行中的 QVMConsole 实例
• 有效的 API Key（从 QVMConsole 管理面板获取）

安装

方式一：通过 npx 直接使用（推荐）

无需安装，直接使用：

npx @qvmconsole/mcp-server

第一次运行时会自动安装 Python 依赖。

方式二：全局安装

npm install -g @qvmconsole/mcp-server
qvmconsole-mcp

方式三：从源码安装

1. 克隆项目

git clone https://github.com/QVMConsole/MCP_Server.git
cd MCP_Server

2. 安装依赖

pip install -r requirements.txt

配置

方式一：通过环境变量配置（推荐）

直接在 MCP 客户端配置中使用 env 字段，无需额外配置文件：

{
  "mcpServers": {
    "qvmconsole": {
      "command": "npx",
      "args": ["-y", "@qvmconsole/mcp-server"],
      "env": {
        "QVMC_BASE_URL": "http://your-qvmconsole-url:8082",
        "QVMC_API_KEY_ID": "kvm_id_xxxxxxxxxxxxxxxxxx",
        "QVMC_API_KEY": "kvm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

方式二：通过配置文件

# 创建配置文件
cp config/config.example.json config/config.json

编辑 config/config.json：

{
  "qvmconsole": {
    "base_url": "http://your-qvmconsole-url:8082",
    "api_key_id": "kvm_id_xxxxxxxxxxxxxxxxxx",
    "api_key": "kvm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "timeout": 30,
    "verify_ssl": true
  }
}

环境变量说明

变量名	说明	必填
QVMC_BASE_URL	QVMConsole 地址	是
QVMC_API_KEY_ID	API Key ID	是
QVMC_API_KEY	API Key	是
QVMC_TIMEOUT	请求超时时间（秒），默认 30	否
QVMC_VERIFY_SSL	是否验证 SSL 证书，默认 true	否

配置优先级

1. 环境变量（最高优先级）
2. 配置文件 - config/config.json
3. 默认值

获取 API Key

1. 登录 QVMConsole 管理面板
2. 右上角用户下拉框选择安全设置

3. 生成API

4. 将API ID的值复制到QVMC_API_KEY_ID的值 Key 标识的值复制到QVMC_API_KEY的值

在 Claude Desktop 中使用

在 Claude Desktop 的配置文件中添加以下内容：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

使用 npx（推荐）

{
  "mcpServers": {
    "qvmconsole": {
      "command": "npx",
      "args": ["-y", "@qvmconsole/mcp-server"],
      "env": {
        "QVMC_BASE_URL": "http://your-qvmconsole-url:8082",
        "QVMC_API_KEY_ID": "kvm_id_xxxxxxxxxxxxxxxxxx",
        "QVMC_API_KEY": "kvm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

使用全局安装

{
  "mcpServers": {
    "qvmconsole": {
      "command": "qvmconsole-mcp",
      "env": {
        "QVMC_BASE_URL": "http://your-qvmconsole-url:8082",
        "QVMC_API_KEY_ID": "kvm_id_xxxxxxxxxxxxxxxxxx",
        "QVMC_API_KEY": "kvm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

使用源码方式

{
  "mcpServers": {
    "qvmconsole": {
      "command": "python",
      "args": ["/path/to/MCP_Server/src/server.py"],
      "env": {
        "QVMC_BASE_URL": "http://your-qvmconsole-url:8082",
        "QVMC_API_KEY_ID": "kvm_id_xxxxxxxxxxxxxxxxxx",
        "QVMC_API_KEY": "kvm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

配置完成后重启 Claude Desktop 即可使用。

在 Cursor 中使用

在 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "qvmconsole": {
      "command": "npx",
      "args": ["-y", "@qvmconsole/mcp-server"],
      "env": {
        "QVMC_BASE_URL": "http://your-qvmconsole-url:8082",
        "QVMC_API_KEY_ID": "kvm_id_xxxxxxxxxxxxxxxxxx",
        "QVMC_API_KEY": "kvm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

在 Trae IDE 中使用

在 Trae IDE 的 MCP 配置中添加相同的配置，即可在 Trae 中通过 AI 助手管理虚拟机。

可用工具

虚拟机管理

工具名	功能说明
list_templates	列出所有可用的虚拟机模板
list_storage_pools	列出可用的存储位置及可用空间
list_switches	列出所有 VPC 交换机
create_vm_from_template	从模板创建虚拟机
get_vm_info	获取虚拟机详细信息（含密码）
list_vms	列出所有虚拟机
edit_vm	编辑虚拟机配置
vm_power_operation	虚拟机电源操作（启动/关机/重启等）
reset_vm_password	重置虚拟机密码

磁盘管理

工具名	功能说明
add_disk	为虚拟机添加新硬盘
list_disks	列出虚拟机磁盘
resize_disk	扩容虚拟机磁盘

快照管理

工具名	功能说明
list_snapshots	列出虚拟机快照
create_snapshot	创建虚拟机快照
revert_snapshot	恢复虚拟机快照
delete_snapshot	删除虚拟机快照

定时任务

工具名	功能说明
list_vm_schedules	列出定时任务
create_vm_schedule	创建定时任务
delete_vm_schedule	删除定时任务

监控

工具名	功能说明
get_vm_stats	获取实时监控数据

VNC 远程控制

VNC 截图说明

vnc_screenshot 工具返回的是 PNG 格式的屏幕截图预览。使用此功能需要 MCP 客户端及底层 AI 模型支持视觉能力（如 豆包、千问 等多模态模型），否则无法正确解析截图内容。

工具名	功能说明
vnc_status	查看 VNC 状态
vnc_enable	开启 VNC
vnc_expose	切换 VNC 对外暴露状态
vnc_screenshot	截取 VNC 画面（需视觉模型支持）
vnc_click	在 VNC 画面上点击鼠标
vnc_type	在 VNC 中输入文本
vnc_key	按下特殊按键
vnc_move	移动鼠标

使用示例

在支持 MCP 的 AI 客户端中，您可以使用自然语言与虚拟机交互：

自然语言指令	对应操作
"列出所有可用的虚拟机模板"	调用 list_templates
"使用 ubuntu-22.04 模板创建一个虚拟机，名称为 test-vm，2核4G"	调用 create_vm_from_template
"查看 test-vm 的详细信息，包括登录密码"	调用 get_vm_info
"将 test-vm 的内存调整为 8G"	调用 edit_vm
"列出所有虚拟机"	调用 list_vms
"启动 test-vm 虚拟机"	调用 vm_power_operation
"给 test-vm 添加一个 100G 的数据盘"	调用 add_disk
"查看 test-vm 的实时监控数据"	调用 get_vm_stats
"截取 test-vm 的当前画面"	调用 vnc_screenshot

故障排查

API Key 无效

确保您的 API Key 正确且未被撤销，在 QVMConsole 管理面板中检查 API Key 状态。

连接失败

检查：

1. QVMConsole 服务是否运行
2. base_url 配置是否正确
3. 网络连接是否正常
4. 防火墙设置是否允许连接

权限不足

确保 API Key 对应的用户有足够的权限执行相应操作。

安全提示

• 妥善保管您的 API Key
• 建议在生产环境使用 HTTPS
• 为 MCP Server 创建专用的受限权限用户

相关链接

• GitHub 仓库
• QVMConsole 官网
• MCP Protocol