Ubuntu 虚拟机控制 j04783993-prog/dsh-ubuntu-vm-control

dsh-ubuntu-vm-control

Ubuntu 虚拟机控制 MCP server——让任意支持 MCP 的客户端（dsh / Claude Desktop / Cursor / Trae…）直接操作一台 Ubuntu 桌面虚拟机：跑命令、开终端、点鼠标、敲键盘，截图存成真实图片文件。同时提供 DeepSeek Harness 的一键集成。

适合需要图形界面的场景：做安全实验、复现漏洞、点网页表单、给报告配图。纯 SSH 只能拿到文字输出，这个能拿到屏幕。

MCP 客户端 ──stdio──> server.py (Python) ──SSH──> Ubuntu VM ├── xdotool （键鼠） ├── scrot （截图） └── wmctrl （窗口）

前置条件

| 项 | 要求 |
| Python | 3.8 或更高，在 PATH 里 |
| MCP 客户端 | dsh、Claude Desktop、Cursor、Trae 等任意支持 stdio MCP 的客户端 |
| 被控机 | Ubuntu，X11 会话 |
| 被控机软件 | sudo apt install -y xdotool scrot wmctrl openssh-server |
| SSH | 密钥免密登录（插件用 BatchMode，不会弹密码框） |

没有 Xorg 会话？Ubuntu 25.10 起 GNOME 移除了 Xorg。装个 Xfce 即可：sudo apt install -y xfce4，登录时选 Xfce Session。

安装

两种方式，按你用的客户端选。

方式一：作为 MCP server 接入任意客户端（推荐）

不用克隆仓库，也不依赖 dsh。先把包装到全局：

npm i -g dsh-ubuntu-vm-control

然后在客户端配置里加一条 stdio server。

Windows 必须用 node 指向包内入口——MCP 客户端是直接启动进程、不经过 shell，写 npx 会因为 .cmd 无法执行而报 ENOENT：

{
"mcpServers": {
"ubuntu-vm-control": {
"command": "node",
"args": [
"C:\\Users\\<用户名>\\AppData\\Roaming\\npm\\node_modules\\dsh-ubuntu-vm-control\\bin\\cli.js", "serve" ],
"env": { "VM_HOST": "192.168.1.10", "VM_USER": "ubuntu" }
}
}
}

真实路径用 npm root -g 查到目录后，拼上 \dsh-ubuntu-vm-control\bin\cli.js。

macOS / Linux 可以直接用 npx：

{
"mcpServers": {
"ubuntu-vm-control": {
"command": "npx",
"args": ["-y", "dsh-ubuntu-vm-control", "serve"],
"env": { "VM_HOST": "192.168.1.10", "VM_USER": "ubuntu" }
}
}
}

方式二：装成 dsh 插件

git clone https://github.com/j04783993-prog/dsh-ubuntu-vm-control.git
cd dsh-ubuntu-vm-control

Windows：双击 install.cmd

Linux / macOS：

python3 install.py

安装脚本会做三件事：

1. 把 server.py 复制到 ~/.dsh-ubuntu-vm-control/（稳定位置，之后删掉仓库也不影响）
2. 在 ~/.dsh/profiles/desktop/cordis.patch.yml 里写入一条 MCP 配置，路径是安装时算出来的绝对路径
3. 改文件前自动备份

常用参数：

python install.py --profile web # 装到别的 profile
python install.py --python /usr/bin/python3 # 指定解释器
python install.py --dry-run # 只看结果，不写文件
python install.py --uninstall # 移除配置

装完完全退出 dsh 再重新打开（不是刷新窗口）。

注意：npm i dsh-ubuntu-vm-control 只是把包装下来，不会自动注册成 dsh 插件。
想用 dsh 集成，装完还要执行一次 npx dsh-ubuntu-vm-control install（等价于 python install.py）。

npm 包的其它子命令：

npx dsh-ubuntu-vm-control install --profile web # 装到别的 profile
npx dsh-ubuntu-vm-control install --dry-run # 只看结果，不写文件
npx dsh-ubuntu-vm-control serve # 以 MCP stdio 方式启动服务

配置被控机

方式一：配置文件 ~/.dsh-ubuntu-vm-control/config.json

{
"host": "192.168.1.10",
"user": "ubuntu",json
"key_path": "~/.ssh/id_ed25519",
"display": ":0",
"screenshot_dir": "~/vm-shots",
"max_width": 1600
}

方式二：环境变量 bash
VM_HOST=192.168.1.10
VM_USER=ubuntu
VM_SSH_KEY=~/.ssh/id_ed25519

优先级：环境变量 > 用户配置文件 > 默认值。

mode 一般不用填：配了 host 就自动走 ssh，没配 host 则认为是跑在被控机本身上（local）。
所以在 macOS / Linux 上控制远端虚拟机时，务必确认 host 已配置，否则会被当成操作本机。

配好之后让智能体调一次 vm_status，它会报告连接状态、会话类型（X11/Wayland）、缺失的工具和分辨率。

提供的工具（18 个）

| 工具 | 说明 |
| vm_status | 连接与环境自检（先调这个） |
| execute_command | 在虚拟机上执行 shell 命令 |
| open_terminal | 在桌面上打开一个真实终端窗口 |
| take_screenshot | 截图并保存为图片文件；window 只截某个窗口，region 截矩形 |
| list_screenshots | 列出已保存的截图 |
| click / move_mouse / drag_mouse | 鼠标操作 |
| type_text / press_key / press_hotkey / scroll | 键盘操作 |
| get_active_window_title / list_windows / focus_window | 窗口管理 |
| get_screen_info | 分辨率与显示协议 |
| upload_file / download_file | 与虚拟机互传文件 |

截图为什么好用

take_screenshot(window="Firefox") 会先激活那个窗口，再沿窗口管理器的外框取几何（含标题栏），
只截这一块——画面干净，直接能放进报告。
text
截图已保存（103 KB，方式：窗口「Firefox」/ scrot） C:\Users\you\vm-shots\exp1-browser.jpg

免密 SSH bash

Linux / macOS

ssh-copy-id -i ~/.ssh/id_ed25519.pub ubuntu@192.168.1.10

Windows (CMD)

type %USERPROFILE%\.ssh\id_ed25519.pub | ssh ubuntu@192.168.1.10 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

验证：ssh -o BatchMode=yes ubuntu@192.168.1.10 echo ok 直接返回 ok。

排错

| 现象 | 原因 |
| MCP 面板里没有 ubuntu，0 个工具 | dsh 没重启；或 cordis.patch.yml 里没有本插件的条目（重跑 install.py） |
| SSH 认证失败 | 没配免密，或 key_path 指错了 |
| 连不上 ... Connection refused | IP 变了 / VM 没开机 / 22 端口被拦 |
| 截图全黑或报错 | Wayland 会话（切 Xorg 或装 Xfce）；或桌面锁屏 |
| xdotool 无反应 | 同上，Wayland 下不可用 |
| 找不到 Python 3 | 装 Python 3.8+，或 install.py --python <绝对路径> 重装一次 |

vm_status 的返回会直接告诉你缺什么，先调它。

卸载

两种安装方式对应不同步骤。

npm 模式（方式一）：
bash
npm uninstall -g dsh-ubuntu-vm-control

再删掉各客户端配置里的 ubuntu-vm-control 条目。

install.py 模式（方式二）： bash
python install.py --uninstall
rm -rf ~/.dsh-ubuntu-vm-control

两种模式互斥：npm 模式的代码在全局 node_modules，install.py 模式的代码在 ~/.dsh-ubuntu-vm-control/。
混用会出现「装了但不生效」或重复注册。

原理

- MCP 服务是一个零依赖的 Python 脚本（只用标准库），SSH 走系统自带的 OpenSSH 客户端
- 安装脚本往 dsh 的 loader 配置里插一条 @deepseek-ai/dsh-mcp-client 条目，指向 ~/.dsh-ubuntu-vm-control/server.py，由 dsh 自己负责拉起和注册工具
- 因此升级 dsh 不会影响它，也不需要编译，更没有 npm 依赖

License

MIT