# VM MCP

A portable MCP server for controlling VMware Workstation virtual machines from an AI client.

让 Codex 等支持 MCP 的 AI 客户端查看虚拟机画面、操作鼠标键盘、执行命令、管理电源和快照。

VM MCP 在你的 Windows 电脑上运行，通过 MCP（Model Context Protocol）把 VMware 的操作能力提供给 AI。你用自然语言描述任务，AI 调用工具观察虚拟机、执行操作并查看结果。Windows 和 Linux 虚拟机可以同时配置，每台机器使用独立名称。

适合虚拟机实验、Windows Server / Linux 学习、软件安装与配置、故障排查，以及修改前保存快照、完成后验证结果的工作。想学习图形界面步骤时，可以明确要求 AI：“尽量通过图形界面完成，并记录每一步点哪里；批量操作可以用命令，注明使用了什么命令。”

## 下载和开始使用

首次公开版本为 **v0.1.0 测试版**。普通用户请在 [Releases（发布版本）](https://github.com/2143shi/vm-mcp/releases/tag/v0.1.0) 中下载 `VM-MCP-Windows-x64.zip`。

1. 安装 VMware Workstation，准备已有虚拟机。
2. 完整解压程序包，保留 `VM-MCP.exe` 和 `_internal` 文件夹在一起。
3. 双击 `VM-MCP.exe`，自动检测虚拟机；找不到时点“选择 VMX 文件”。
4. 选择虚拟机，填写 AI 使用的名称、系统登录用户名和密码，点“保存连接”。
5. 首次开启图形控制台时，先正常关闭虚拟机，再点“开启图形控制台”，完成后启动虚拟机。
6. 点“连接到 Codex”，重启 Codex 后开始使用。其他 MCP 客户端可点“导出其他 AI 连接配置”，按该客户端的 MCP 设置方式导入。

普通用户不需要安装 Python、Git 或 pip。程序包不包含 VMware、虚拟机磁盘和快照。

## 可以完成的操作

| 能力 | 内容 |
|---|---|
| 图形设置窗口 | 双击打开连接设置，选择机器、保存登录信息、开启控制台、连接 AI 客户端 |
| 自动发现虚拟机 | 检测 VMware 库、默认虚拟机目录和正在运行的机器；支持手动选择其他盘上的 VMX |
| 多虚拟机管理 | Windows / Linux 机器分别命名、保存连接，AI 可按名称选择目标 |
| 看画面 | 返回虚拟机当前控制台图像和分辨率 |
| 操作 GUI | 鼠标移动、单击、双击、右键、拖拽、滚轮、键盘输入、快捷键 |
| 连续动作 | 一次最多50个动作，返回最终画面；界面加载和焦点变化后重新观察 |
| Windows 中文粘贴 | 向已观察并聚焦的 Windows 桌面输入框粘贴中文或长文本；需要 Tools 和对应登录会话 |
| 登录框输入 | 使用已保存的用户名或密码填写已经观察、聚焦的登录框，工具结果不返回凭据文本 |
| 执行命令 | Windows CMD / PowerShell，Linux Shell，通过 VMware Tools 执行 |
| 电源管理 | 启动、正常关机、重启、暂停、恢复、挂起、查看状态 |
| 快照管理 | 创建、命名、列出、恢复和删除 VMware 快照 |
| 长命令任务 | 返回任务编号，持续读取执行状态和输出；MCP 重启后仍能查询同一命令任务 |
| 电源和快照进度 | 通过操作编号查询同一次修改；结果不明时先检查状态，避免重复执行 |
| 运行状态查询 | 查看已配置机器、运行列表、VMware Tools 状态和 Tools 获取到的 IP |
| 本地凭据保存 | 应用凭据库用 Windows DPAPI 加密；配置更新可自动重载，也可手动刷新连接 |
| 客户端连接 | 图形窗口连接 Codex，或导出其他兼容 stdio MCP 客户端的连接配置 |
| 可移植程序包 | 完整文件夹可换路径复制，普通用户不需要额外安装 Python |

例如可以对 AI 说：

- “看一下 windows2 当前画面，打开浏览器。”
- “先观察 windows1 的桌面，再通过图形界面配置 IIS，记录点过的位置。”
- “在 linux1 查询磁盘空间，把命令和输出告诉我。”
- “修改前先创建快照，名字叫安装软件之前。”
- “恢复到安装软件之前，再启动虚拟机。”
- “这个任务如果还在运行，继续读取原来的任务，不要再执行一遍。”

MCP 提供操作工具；AI 的判断和排错效果还取决于模型、任务说明和权限设置。

## 系统要求和已验证范围

- 宿主机：Windows x64，VMware Workstation。当前没有验证 VirtualBox、macOS 或 Linux 宿主机。
- 命令通道：虚拟机内 VMware Tools / open-vm-tools 正在运行，并提供有效的系统登录信息。
- GUI通道：虚拟机开启 VMware VNC 控制台。锁屏或息屏时看到的就是当前锁屏或黑色画面。
- Windows 中文粘贴需要所保存账户的交互桌面；其他非ASCII输入可使用虚拟机内输入法。

已在一台Windows宿主机的四台虚拟机上完成实际画面、鼠标键盘、命令、任务恢复和快照验证。可移植包完成换路径、全新设置目录及无Python PATH测试；**尚未在第二台实体电脑实测**。

## 换电脑与本地数据

新电脑安装 VMware Workstation，复制完整程序文件夹，双击程序。重新发现虚拟机，必要时选择一次 VMX，并重新输入登录信息；不要求相同的用户名、硬盘路径、IP或分辨率。程序换位置后，重新点“连接到 Codex”或导出连接配置，让客户端使用新位置的程序。

本机设置、凭据和运行记录放在 `%LOCALAPPDATA%\VM-MCP`，不会随发布包提供。应用凭据库使用当前Windows账户的DPAPI加密，不能直接迁移给另一台电脑或账户。VMware VNC密码另外写入所选虚拟机的VMX设置；迁移或分享虚拟机时应检查该文件。

默认快照只保存系统和磁盘，不保存内存；恢复后需要启动虚拟机。需要保留桌面和内存时，可明确要求包含内存的快照。迁移快照应携带完整虚拟机目录和磁盘链。

## 常见问题

| 情况 | 处理方法 |
|---|---|
| 列表中没有虚拟机 | 点“重新检测”；仍未找到时点“选择 VMX 文件”，选择该虚拟机的 `.vmx` |
| 提示未找到 VMware | 确认宿主机已安装 VMware Workstation；开发者也可用 `VMRUN_PATH` 指定 `vmrun.exe` |
| 不能开启图形控制台 | 在 VMware 中正常关闭该虚拟机，再点“开启图形控制台”，完成后重新启动 |
| 画面是黑屏或锁屏 | 检查虚拟机当前显示状态，按需要唤醒或登录，再观察 |
| 命令执行失败 | 检查 VMware Tools / open-vm-tools、保存的登录信息，以及该账户执行目标命令的权限 |
| Windows 中文不能粘贴 | 确认 VMware Tools 正在运行，保存的账户已登录交互桌面，并先聚焦目标输入框 |
| Codex 没出现工具 | 再点一次“连接到 Codex”并重启 Codex，检查客户端 MCP 连接状态 |
| 提示画面已过期 | 重新观察当前画面，使用新的 `observation_id`；不要重复发送上一组动作 |

## AI 工具使用约定

GUI流程：`console_observe` → 查看画面 → `console_action` / `console_batch`。必须使用该虚拟机最新的 `observation_id`。出现未知结果后重新观察，不盲目重放。

命令流程：`guest_command` 返回 `job_id`；未完成时用 `command_read` 读取同一任务。

电源和快照修改：`vm_action` 返回 `operation_id`；通过 `vm_operation_read` 确认成功，再做依赖它的操作。状态、列表、快照列表、Tools 和 IP 查询直接返回结果。

项目提供以下 **13 个 MCP 工具**：

| 工具 | 用途 |
|---|---|
| `lab_status` | 查询配置和 VMware 当前运行列表 |
| `vm_discover` | 发现虚拟机，或通过指定 VMX 注册机器 |
| `lab_reload` | 重新加载配置与凭据，重置控制台连接；之后重新观察 |
| `credential_set` | 更新已配置机器的用户名、登录密码或 VNC 密码，保存到加密凭据库 |
| `console_observe` | 获取当前画面、尺寸和新的观察编号 |
| `console_action` | 根据最新观察执行一次鼠标或键盘动作，返回操作后的画面 |
| `console_batch` | 执行1至50个可预期的短动作，返回最后的画面 |
| `console_paste` | 向 Windows 桌面粘贴 Unicode 文本 |
| `console_type_saved` | 向已聚焦的登录框输入保存的用户名或密码 |
| `guest_command` | 通过 Tools 执行命令，返回任务编号和当前结果 |
| `command_read` | 继续读取同一个命令任务的状态与输出 |
| `vm_action` | 电源、快照、Tools、IP 和运行状态操作 |
| `vm_operation_read` | 继续查询同一个电源或快照修改的结果 |

开发者可以使用 `VM-MCP.exe --diagnose` 查看发现结果和连接配置；`--stdio` 启动 MCP 服务；`--register-codex` 写入 Codex 连接配置。普通用户直接使用图形设置窗口即可。

## 从源码开发和构建

以下只供开发者使用，普通用户下载 Releases 中的程序包即可。

需要 Windows x64、Python 3.12 和本机 .NET Framework C# 编译器；VMware 运行时库由本机安装的 VMware 提供，项目不附带 VMware DLL。

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests
.\build.ps1
```

构建输出在 `dist\VM-MCP`。`native-vix.cs` 编译为小型32位适配器，调用宿主机上的 VMware VIX；主程序为Windows x64。

构建脚本也会复制项目和第三方许可证。随仓库提供的第三方清单记录 v0.1.0 发布包使用的组件；更新依赖后，发布者应按实际打包的版本更新清单和许可证文件。

```powershell
python verify.py --exe .\dist\VM-MCP\VM-MCP.exe
```

`--live` 另外读取已配置虚拟机的实际状态、快照和图像，不自动修改虚拟机。

## 许可证

本项目代码采用 MIT 许可证，见 `LICENSE`。第三方依赖保留各自许可证，见 `THIRD_PARTY_NOTICES.md` 和程序包中的许可证文件。