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（发布版本） 中下载 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、虚拟机磁盘和快照。

Related MCP server: vmware-mcp

可以完成的操作

例如可以对 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设置；迁移或分享虚拟机时应检查该文件。

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

常见问题

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 工具：

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

从源码开发和构建

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

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

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 发布包使用的组件；更新依赖后，发布者应按实际打包的版本更新清单和许可证文件。

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

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

许可证

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