VMware Workstation Pro MCP Server

通过 REST API、vmrun 和 vmcli 控制 VMware Workstation Pro 虚拟机的 MCP 服务器。

功能特性

136 个工具，覆盖 VMware Workstation Pro 全部自动化能力：

来源	工具数	描述
本地状态与任务	11	当前 VM、注册表列举、电源状态、异步任务、客户机凭据
REST API	18	虚拟机管理、网卡、共享文件夹、端口转发
vmrun	46	电源、快照、克隆、客户机文件/进程操作、设备
vmcli	61	芯片组、磁盘、网卡、SATA、NVMe、串口、VProbes

计数与 server.py 的 list_tools() 逐条对应（按分节横幅统计）。

VM 选择器与当前 VM

vm_id 在所有工具中都是可选的：省略时使用当前 VM（由 vm_select 设定）；显式传入并成功解析后，该 VM 成为当前 VM。选择器按顺序匹配：

.vmx 路径（文件必须存在，否则立即报 missing_vmx）
UUID（对空格/连字符不敏感）
DisplayName（大小写不敏感，精确匹配）
DisplayName / vmx 路径的唯一子串
仅 REST 工具：上述都未命中时回退到 vmrest 的 VM 列表

无当前 VM 且注册表恰好 1 台时自动选中；多台时返回 ambiguous 并列出候选。VMWARE_DEFAULT_VM 可在启动后第一次解析时把一台 VM 固定为当前。

身份与状态来源是 %APPDATA%\VMware\inventory.vmls（可用 VMWARE_INVENTORY 覆盖）+ vmrun list + vmcli <vmx> Power query。vmrun/vmcli 工具不依赖 vmrest，只有 REST 工具需要。

vm_delete / vmrun_delete 在没有显式 vm_id 且没有当前 VM 时直接拒绝，避免误删。

客户机凭据（密码）

vmrun 的 *InGuest 命令和 vmcli 的 Guest * 命令都要客户机 OS 的用户名/密码。首次调用没凭据时直接返回 auth_required，不猜、不空跑：

{"ok": false, "status": "auth_required", "error_type": "auth_required",
 "error": "guest_ls needs guest credentials for Windows 11 x64; ask the user for the guest OS username and password, then call vm_credentials_set with vm_id=\"Windows 11 x64\", user, password",
 "hint": "call vm_credentials_set with {vm_id, user, password}"}

按提示向用户要密码，vm_credentials_set {vm_id, user, password} 存一次，之后同一 VM 的客户机工具自动复用；调用参数里显式给的 user/password 优先于存储值。密码用 Windows DPAPI（当前用户范围）加密后存到 %LOCALAPPDATA%\vmware-mcp\credentials.json（VMWARE_CREDENTIALS 可改路径），文件内没有明文；vm_credentials_status 只回显用户名和时间，vm_credentials_clear 删除。密码被客户机拒绝时同样回 auth_required（CLI 原文附在 error 里），重新 set 即可。

vmrun_var_read / vmrun_var_write 只有 guestEnv / guestVar 需要凭据，runtimeConfig 不需要。

长操作与超时

每条 CLI 调用都有硬超时；超时只杀 CLI 进程本身（不杀进程树，避免连带杀掉 vmware-vmx.exe），错误信息会提示用 vm_status / job_status 复查。长操作在软等待（默认 2.5s）内没完成时返回 job_id，用 job_wait / job_status / job_cancel 跟进。

环境变量	默认	用途
`VMWARE_TIMEOUT`	30	普通查询/配置（秒）
`VMWARE_POWER_TIMEOUT`	300	start/stop/reset/suspend/pause/unpause
`VMWARE_LONG_TIMEOUT`	1800	clone/delete/upgrade/install tools/snapshot/disk/template
`VMWARE_GUEST_TIMEOUT`	120	客户机 run/copy/file 操作
`VMWARE_POWER_QUERY_TIMEOUT`	5	`vmcli <vmx> Power query`
`VMWARE_LIST_TIMEOUT`	5	`vmrun list`
`VMWARE_REST_TIMEOUT`	10	vmrest HTTP 请求
`VMWARE_SOFT_WAIT_MS`	2500	MCP 工具软等待（毫秒；0 = 一律返回 job）
`VMWARE_CREDENTIALS`	`%LOCALAPPDATA%\vmware-mcp\credentials.json`	客户机凭据存储路径

响应格式

所有工具返回 JSON 信封（成功 ok:true，失败 ok:false + isError:true）：

{"ok": true, "operation": "power_query", "status": "succeeded",
 "target": {"name": "Windows 11 x64", "uuid": "564D4FB7D945E2794873A904C2731E70",
            "vmx": "D:\\VMs\\Windows 11 x64\\Windows 11 x64.vmx",
            "power": "on", "registered": true, "running": true, "current": true},
 "duration_ms": 412, "result": "PowerState: on"}

status：成功侧 succeeded | noop | running；失败侧 failed | timed_out | busy | not_found | ambiguous | cancelled | auth_required
未在软等待内完成时返回 job_id + hint，不含 result
预检会拒绝与电源状态矛盾的调用（客户机工具要求开机、ethernet_set_pci_slot 要求关机），并把“已开机又 start”这类操作变成 noop
解析类错误附带 candidates；同一 VM 上并发的破坏性操作返回 busy 和活动 job id

环境要求

VMware Workstation Pro 17+
Python 3.10+
vmrest 服务运行中（REST API 工具需要）

安装

git clone https://github.com/xiaobfly/vmware-mcp
cd vmware-mcp
python -m venv .venv
.venv\Scripts\pip install -e .

omp 插件清单把命令固定为 ./.venv/Scripts/vmware-mcp.exe，所以必须装在本仓库的 .venv 里。

配置

启动 vmrest 服务：

# 首次配置
"C:\Program Files (x86)\VMware\VMware Workstation\vmrest.exe" -C

# 启动服务
"C:\Program Files (x86)\VMware\VMware Workstation\vmrest.exe"

添加到 Claude Code：

claude mcp add vmware-mcp \
  -e VMWARE_USERNAME=your_username \
  -e VMWARE_PASSWORD=your_password \
  -- vmware-mcp

添加到 omp（一键）

仓库自带 omp 插件清单：package.json + Agent Plugins 1.0.0 的 plugin.json / mcp.json（声明 mcpServers.vmware，命令用相对路径 ./.venv/Scripts/vmware-mcp.exe）。先完成上面的安装，然后：

cd vmware-mcp
omp plugin install .

插件根目录就是仓库目录（linked，不复制），改代码后无需重装插件
omp plugin list 查看、omp plugin uninstall vmware-mcp 移除、omp plugin doctor 自检
已在用户级 ~/.omp/agent/mcp.json 手动配过 vmware 的，先删掉那条再装插件，避免同名 server 重复
重启 omp 生效，工具前缀 mcp__vmware_*（136 个）
VMware 不在 D:\VMware\... 时改 mcp.json 里的 VMRUN_PATH / VMCLI_PATH
非交互 omp -p 的首轮可能早于 MCP 连接完成（默认启动窗口 250ms）：需要时调大 mcp.startupTimeoutMs，例如 omp --config E:\omp.yml -p ...，omp.yml 写 mcp: { startupTimeoutMs: 8000 }

手动配置（与插件二选一）：用户级 ~/.omp/agent/mcp.json。$schema 必须存在且等于下面这行，否则整个文件被判为 disabled：

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "vmware": {
      "command": "E:\\tools\\vmware-mcp\\.venv\\Scripts\\vmware-mcp.exe",
      "env": {
        "VMRUN_PATH": "D:\\VMware\\VMware Workstation\\vmrun.exe",
        "VMCLI_PATH": "D:\\VMware\\VMware Workstation\\vmcli.exe"
      },
      "timeout": 600000
    }
  }
}

timeout 单位毫秒，600000 覆盖 clone / disk extend 等长操作；工具内部仍按软等待返回 job_id
VMRUN_PATH / VMCLI_PATH 只在 VMware 装在非默认路径时需要；REST 工具另需 VMWARE_USERNAME / VMWARE_PASSWORD（vmrun/vmcli 工具不需要）

工具列表

本地状态与任务工具

工具	描述
`vm_list`	列出已注册虚拟机（inventory.vmls + vmrun list，不需要 vmrest）
`vm_select`	固定当前 VM，之后可省略 `vm_id`
`vm_current`	显示当前 VM 与注册表候选
`vm_status`	刷新一台或全部 VM 的电源状态（不需要 vmrest）
`vm_credentials_set`	存客户机用户名/密码（DPAPI 加密），后续客户机工具自动复用
`vm_credentials_status`	列出已存凭据的 VM（只回显用户名）
`vm_credentials_clear`	删除某 VM 的客户机凭据
`job_list`	列出运行中/最近完成的任务
`job_status`	查询任务状态与结果
`job_wait`	等待任务完成（默认 30s，最大 300s）
`job_cancel`	取消任务（终止 CLI 进程）

REST API 工具

工具	描述
`vm_get`	获取虚拟机设置
`vm_create`	克隆虚拟机
`vm_delete`	删除虚拟机
`vm_update`	更新虚拟机 CPU/内存
`vm_power_get`	获取电源状态
`vm_power_set`	设置电源状态（开/关/挂起/暂停）
`vm_nic_list`	列出网络适配器
`vm_nic_create`	创建网络适配器
`vm_nic_delete`	删除网络适配器
`vm_ip_get`	获取虚拟机 IP 地址
`vm_folder_list`	列出共享文件夹
`vm_folder_create`	创建共享文件夹
`vm_folder_delete`	删除共享文件夹
`network_list`	列出虚拟网络
`network_create`	创建虚拟网络
`network_portforward_list`	列出端口转发
`network_portforward_set`	设置端口转发
`network_portforward_delete`	删除端口转发

vmrun 工具

工具	描述
`vmrun_list`	列出运行中的虚拟机
`vmrun_start`	启动虚拟机
`vmrun_stop`	停止虚拟机（软/硬）
`vmrun_reset`	重置虚拟机
`vmrun_suspend`	挂起虚拟机
`vmrun_pause`	暂停虚拟机
`vmrun_unpause`	恢复暂停的虚拟机
`vmrun_clone`	克隆虚拟机（完整/链接）
`vmrun_upgrade`	升级虚拟机格式
`vmrun_delete`	删除虚拟机
`vmrun_snapshot_list`	列出快照
`vmrun_snapshot_take`	创建快照
`vmrun_snapshot_delete`	删除快照
`vmrun_snapshot_revert`	恢复快照
`vmrun_file_exists`	检查客户机文件是否存在
`vmrun_dir_exists`	检查目录是否存在
`vmrun_ls`	列出客户机目录
`vmrun_mkdir`	在客户机创建目录
`vmrun_rmdir`	删除客户机目录
`vmrun_rm`	删除客户机文件
`vmrun_rename`	重命名客户机文件
`vmrun_copy_to`	复制文件到客户机
`vmrun_copy_from`	从客户机复制文件
`vmrun_temp_file`	在客户机创建临时文件
`vmrun_run`	在客户机运行程序
`vmrun_script`	在客户机运行脚本
`vmrun_ps`	列出客户机进程
`vmrun_kill`	终止客户机进程
`vmrun_shared_enable`	启用共享文件夹
`vmrun_shared_disable`	禁用共享文件夹
`vmrun_shared_add`	添加共享文件夹
`vmrun_shared_remove`	移除共享文件夹
`vmrun_shared_set`	设置共享文件夹状态
`vmrun_device_connect`	连接设备
`vmrun_device_disconnect`	断开设备
`vmrun_var_read`	读取虚拟机变量
`vmrun_var_write`	写入虚拟机变量
`vmrun_screenshot`	截取屏幕
`vmrun_keystrokes`	发送按键
`vmrun_tools_install`	安装 VMware Tools
`vmrun_tools_state`	检查 Tools 状态
`vmrun_guest_ip`	获取客户机 IP
`vmrun_host_networks`	列出主机网络
`vmrun_portforward_list`	列出端口转发
`vmrun_portforward_set`	设置端口转发
`vmrun_portforward_delete`	删除端口转发

vmcli 工具

工具	描述
`snapshot_list`	列出快照
`snapshot_take`	创建快照
`snapshot_revert`	恢复快照
`snapshot_delete`	删除快照
`snapshot_clone`	从快照克隆
`guest_run`	运行程序
`guest_ps`	列出进程
`guest_kill`	终止进程
`guest_ls`	列出文件
`guest_mkdir`	创建目录
`guest_rm`	删除文件
`guest_rmdir`	删除目录
`guest_copy_to`	复制到客户机
`guest_copy_from`	从客户机复制
`guest_env`	获取环境变量
`mks_screenshot`	截取屏幕
`mks_send_key`	发送按键序列
`mks_query`	查询 MKS 状态
`chipset_query`	查询 CPU/内存配置
`chipset_set_cpu`	设置 CPU 数量
`chipset_set_memory`	设置内存大小
`chipset_set_cores`	设置每插槽核心数
`tools_query`	查询 Tools 状态
`tools_install`	安装 Tools
`tools_upgrade`	升级 Tools
`template_create`	创建虚拟机模板
`template_deploy`	部署虚拟机模板
`disk_query`	查询磁盘配置
`disk_create`	创建磁盘
`disk_extend`	扩展磁盘
`config_query`	查询配置参数
`config_set`	设置配置参数
`power_query`	查询电源状态
`power_start`	启动虚拟机
`power_stop`	停止虚拟机
`power_pause`	暂停虚拟机
`power_unpause`	恢复虚拟机
`power_reset`	重置虚拟机
`power_suspend`	挂起虚拟机
`ethernet_query`	查询网卡配置
`ethernet_set_type`	设置连接类型
`ethernet_set_present`	设置适配器存在
`ethernet_set_connected`	设置启动时连接
`ethernet_set_device`	设置虚拟设备
`ethernet_set_network`	设置网络名称
`ethernet_set_pci_slot`	设置 PCI 槽位（需虚拟机关机）
`ethernet_purge`	移除适配器
`hgfs_query`	查询共享文件夹（本版 vmcli 的 HGFS setter 已损坏，共享文件夹请用 `vmrun_shared_*`）
`serial_query`	查询串口
`serial_set_present`	设置串口存在
`serial_purge`	移除串口
`sata_query`	查询 SATA 配置
`sata_set_present`	设置 SATA 存在
`sata_purge`	移除 SATA 适配器
`nvme_query`	查询 NVMe 配置
`nvme_set_present`	设置 NVMe 存在
`nvme_purge`	移除 NVMe 适配器
`vprobes_query`	查询 VProbes
`vprobes_enable`	启用 VProbes
`vprobes_load`	加载 VProbes 脚本
`vprobes_reset`	重置 VProbes

许可证

MIT

Name		Name	Last commit message	Last commit date
openspec/changes/vm-state-jobs		openspec/changes/vm-state-jobs
src/vmware_mcp		src/vmware_mcp
tests		tests
.gitignore		.gitignore
README.md		README.md
mcp.json		mcp.json
package.json		package.json
plugin.json		plugin.json
pyproject.toml		pyproject.toml

Navigation Menu

Repository navigation

About

Repository files navigation

VMware Workstation Pro MCP Server

功能特性

VM 选择器与当前 VM

客户机凭据（密码）

长操作与超时

响应格式

环境要求

安装

配置

添加到 omp（一键）

工具列表

本地状态与任务工具

REST API 工具

vmrun 工具

vmcli 工具

许可证

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

VMware Workstation Pro MCP Server

功能特性

VM 选择器与当前 VM

客户机凭据（密码）

长操作与超时

响应格式

环境要求

安装

配置

添加到 omp（一键）

工具列表

本地状态与任务工具

REST API 工具

vmrun 工具

vmcli 工具

许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages