dsh-ubuntu-vm-control
Enables control of an Ubuntu desktop VM over SSH, including running shell commands, opening terminal windows, performing mouse and keyboard actions, managing windows, taking screenshots, and transferring files.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 或更高,在 |
MCP 客户端 | dsh、Claude Desktop、Cursor、Trae 等任意支持 stdio MCP 的客户端 |
被控机 | Ubuntu,X11 会话 |
被控机软件 |
|
SSH | 密钥免密登录(插件用 |
没有 Xorg 会话?Ubuntu 25.10 起 GNOME 移除了 Xorg。装个 Xfce 即可:
sudo apt install -y xfce4,登录时选 Xfce Session。
Related MCP server: lowlevel-computer-use-mcp
安装
两种方式,按你用的客户端选。
方式一:作为 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-controlWindows:双击 install.cmd
Linux / macOS:
python3 install.py安装脚本会做三件事:
把
server.py复制到~/.dsh-ubuntu-vm-control/(稳定位置,之后删掉仓库也不影响)在
~/.dsh/profiles/desktop/cordis.patch.yml里写入一条 MCP 配置,路径是安装时算出来的绝对路径改文件前自动备份
常用参数:
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",
"key_path": "~/.ssh/id_ed25519",
"display": ":0",
"screenshot_dir": "~/vm-shots",
"max_width": 1600
}方式二:环境变量
VM_HOST=192.168.1.10
VM_USER=ubuntu
VM_SSH_KEY=~/.ssh/id_ed25519优先级:环境变量 > 用户配置文件 > 默认值。
mode 一般不用填:配了 host 就自动走 ssh,没配 host 则认为是跑在被控机本身上(local)。
所以在 macOS / Linux 上控制远端虚拟机时,务必确认 host 已配置,否则会被当成操作本机。
配好之后让 agent 调一次 vm_status,它会报告连接状态、会话类型(X11/Wayland)、缺失的工具和分辨率。
提供的工具(18 个)
工具 | 说明 |
| 连接与环境自检(先调这个) |
| 在虚拟机上执行 shell 命令 |
| 在桌面上打开一个真实终端窗口 |
| 截图并保存为图片文件; |
| 列出已保存的截图 |
| 鼠标操作 |
| 键盘操作 |
| 窗口管理 |
| 分辨率与显示协议 |
| 与虚拟机互传文件 |
截图为什么好用
take_screenshot(window="Firefox") 会先激活那个窗口,再沿窗口管理器的外框取几何(含标题栏),
只截这一块——画面干净,直接能放进报告。
截图已保存(103 KB,方式:窗口「Firefox」/ scrot)
C:\Users\you\vm-shots\exp1-browser.jpg免密 SSH
# 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 面板里没有 | dsh 没重启;或 |
| 没配免密,或 |
| IP 变了 / VM 没开机 / 22 端口被拦 |
截图全黑或报错 | Wayland 会话(切 Xorg 或装 Xfce);或桌面锁屏 |
| 同上,Wayland 下不可用 |
| 装 Python 3.8+,或 |
vm_status 的返回会直接告诉你缺什么,先调它。
卸载
两种安装方式对应不同步骤。
npm 模式(方式一):
npm uninstall -g dsh-ubuntu-vm-control再删掉各客户端配置里的 ubuntu-vm-control 条目。
install.py 模式(方式二):
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Control your authorized Windows computers via OAuth: files, shell, apps, and task status.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
A cloud Linux desktop for your AI: browse, click, type, read the screen and run commands.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Ubuntu VMs via SSH, including executing commands, simulating keyboard/mouse input, capturing screenshots, and controlling GUI applications remotely.1-
- AlicenseAqualityBmaintenanceEnables MCP agents to automate real GUI applications on headless desktops, providing background mouse/keyboard control, window/process management, screenshots, and safe human handoff without disturbing the user's desktop.594MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to control a Linux/X11 desktop like a human: see the screen, move the mouse, click UI elements via the accessibility tree, type text, and manage windows.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to see and control an existing Linux X11 desktop over SSH by taking screenshots and performing mouse, scroll, typing, and keyboard-shortcut actions across browsers, terminals, file managers, and other apps.MIT