Skip to main content
Glama
dsh-ubuntu-vm-control

dsh-ubuntu-vm-control

dsh-ubuntu-vm-control

version

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。

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-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",
  "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 个)

工具

说明

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") 会先激活那个窗口,再沿窗口管理器的外框取几何(含标题栏), 只截这一块——画面干净,直接能放进报告。

截图已保存(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 面板里没有 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 模式(方式一):

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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Ubuntu VMs via SSH, including executing commands, simulating keyboard/mouse input, capturing screenshots, and controlling GUI applications remotely.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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