AI导哈

Ubuntu桌面控制服务器

一个MCP服务器，使LLMs能够通过截图和发送鼠标点击来控制Ubuntu桌面，允许AI助手与桌面应用程序进行视觉交互。

  • by charettep
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 charettep/ubuntu-desktop-control-mcp

使用说明

Ubuntu桌面控制MCP服务器

MCP（模型上下文协议）服务器，使LLM能够通过截图和发送鼠标点击来控制您的Ubuntu桌面。这允许AI助手与您的桌面应用程序进行视觉交互。

⚡ 新：优化生产工作流程

速度提高5倍，精度提高5倍！ 现在使用与Anthropic的计算机使用API相同的优化技术：

  • 📸 智能屏幕截图：自动降采样到1280x720（小5倍）
  • 🎯 编号元素：通过叠加的ID一目了然地查看可点击的内容
  • 🤖 AT-SPI集成：使用可访问性API自动检测UI元素
  • 📐 百分比坐标：分辨率无关的定位（不再有像素狩猎！）
  • ⚡ 工作流批处理：在一次MCP调用中执行多个操作
  • 🎪 元素缓存：直接元素交互-“点击元素#5”

示例-旧方式（8+个调用，~15秒）：

take_screenshot() → analyze → grid overlay → zoom quadrant → find pixel → click → miss

示例-新方式（1次通话，约3秒）：

take_screenshot() → "I see Pinta is element #5" → click_screen(element_id=5) → ✓

看 README.md 了解全部细节。

特性

  • 📸 电脑屏幕截图工具：带自动元素检测的带注释屏幕截图
  • 🔢 元素检测：AT-SPI+CV回退，用于强大的UI元素识别
  • 🖱️ 智能点击：按元素ID或百分比坐标单击
  • ⌨️ 键盘控制：键入文本并按按键/热键
  • 🎯 鼠标移动：使用动画平滑光标定位
  • 🚀 工作流批处理：在单个MCP调用中执行多步骤任务
  • 📊 诊断：显示缩放检测、警告和建议

快速开始

1.先决条件

  • Ubuntu Linux（需要X11，Wayland不完全支持）
  • Python 3.9+

2.安装

来自PyPI（推荐）

pip install ubuntu-desktop-control

来自源头

# Clone repository
git clone https://github.com/charettep/ubuntu-desktop-control-mcp.git
cd ubuntu-desktop-control-mcp

# Install system dependencies (requires sudo)
chmod +x scripts/install.sh
./scripts/install.sh

# Install Python dependencies
pip install -e .

配置

克劳德代码

Installation Methods

方法1:CLI（推荐）

claude mcp add --transport stdio ubuntu-desktop-control -- \
  ubuntu-desktop-control

方法2：手动配置

编辑 ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ubuntu-desktop-control": {
      "command": "ubuntu-desktop-control",
      "args": []
    }
  }
}

VS代码内部人员

Installation Methods

方法1:MCP命令

  1. 打开命令选项板(Ctrl+Shift+P)
  2. 跑 MCP: Open Workspace Folder Configuration
  3. 在下面添加服务器配置。

方法2：手动配置

创建 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "ubuntu-desktop-control": {
      "type": "stdio",
      "command": "ubuntu-desktop-control",
      "args": []
    }
  }
}

Codex CLI

Installation Methods

方法1:CLI

codex mcp add ubuntu-desktop-control -- \
  ubuntu-desktop-control

方法2：手动配置

编辑 ~/.config/codex/config.toml:

[mcp_servers.ubuntu-desktop-control]
type = "stdio"
command = "ubuntu-desktop-control"
args = []

工具

核心能力

工具 说明
take_screenshot 使用带注释的元素捕获桌面（每个显示器可选）。
click_screen 按元素ID或百分比坐标单击（每个监视器支持）。
move_mouse 按元素ID或百分比坐标移动光标（每个监视器支持）。
drag_mouse 按住鼠标按钮的同时将光标拖动到坐标。
type_text 使用键盘键入文本。
press_key 按特定键（例如“enter”、“esc”）。
press_hotkey 同时按下组合键（例如Ctrl+Shift+C）。
get_screen_info 获取屏幕尺寸和显示服务器类型（X11/Wayland）。
get_display_diagnostics 解决缩放和坐标不匹配的问题。
map_GUI_elements_location 使用计算机视觉检测和映射UI元素（hitbox）。
convert_screenshot_coordinates 将屏幕截图中的像素转换为逻辑点击坐标。
list_prompt_templates 列出可用的提示模板（适用于没有本机提示支持的客户端）。
execute_workflow 执行一批操作（截图/点击/移动/键入/等待）。

提示渲染工具

这些工具允许没有本机提示支持的客户端（如Codex CLI）将提示模板呈现为文本。

工具 说明
render_prompt_baseline_display_check 渲染基线显示检查提示。
render_prompt_capture_full_desktop 渲染完整的桌面捕获提示。
render_prompt_capture_region_for_task 渲染区域捕获提示。
render_prompt_convert_screenshot_coordinates 渲染坐标转换提示。
render_prompt_safe_click 渲染安全单击提示。
render_prompt_hover_and_capture 渲染悬停和捕捉提示。
render_prompt_coordinate_mismatch_recovery 呈现不匹配的恢复提示。
render_prompt_end_to_end_capture_and_act 呈现端到端工作流提示。

提示

提示 描述
baseline_display_check 在开始任务之前，请检查显示设置和缩放比例。
capture_full_desktop 捕获并总结整个桌面状态。
capture_region_for_task 捕捉特定区域进行详细检查。
safe_click 通过安全检查和缩放意识进行点击。
hover_and_capture 悬停以显示UI元素，然后捕获。
coordinate_mismatch_recovery 诊断并修复错过的点击。
end_to_end_capture_and_act 计划并执行一个完整的交互循环。

配置和定制

环境变量

服务器依赖于标准的Linux/X11环境变量来定位桌面会话并与之交互。

变量 描述 默认值
DISPLAY X11显示标识符。服务器需要知道 哪个 屏幕控制。 :0
XDG_SESSION_TYPE 用于检测是否在X11或Wayland上运行。 unknown
XAUTHORITY X11权限文件的路径。如果从不同的用户上下文（例如sudo、docker）或通过SSH运行，则需要此项。 ~/.Xauthority
UDC_FORCE_COORDS 强制坐标点击（禁用AT-SPI动作点击）。 未设置

传递环境变量

您可以在MCP客户端配置中自定义这些变量。

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "ubuntu-desktop-control": {
      "command": "ubuntu-desktop-control",
      "args": [],
      "env": {
        "DISPLAY": ":0",
        "XAUTHORITY": "/home/user/.Xauthority"
      }
    }
  }
}

VS代码(.vscode/mcp.json)

{
  "servers": {
    "ubuntu-desktop-control": {
      "command": "ubuntu-desktop-control",
      "args": [],
      "env": {
        "DISPLAY": ":0"
      }
    }
  }
}

显示比例和坐标

如果单击落在错误的位置，则可能是HiDPI显示缩放不匹配（例如，逻辑1920x1080与物理3840x2160）。

解决：

  1. 自动秤：使用 click_screen(..., auto_scale=True) 让服务器来处理它。
  2. 诊断：运行 get_display_diagnostics() 查看缩放因子。
  3. 元素ID：使用 take_screenshot(detect_elements=True) 并点击通过 element_id 或百分比坐标。

故障排除

Common Issues
  • “截图失败”：确保 gnome-screenshot 或 scrot 已安装(sudo apt install gnome-screenshot).
  • “未安装PyAutoGUI”：确保您正在使用 .venv python
  • Wayland问题：此服务器需要X11。核对 echo $XDG_SESSION_TYPE.如果是“wayland”，请在登录时切换到“Xorg上的GNOME”。
  • 权限不足：运行 xhost +local: 如果您有X11权限问题。

安全

⚠️ 警告：此服务器使LLM可以完全控制您的鼠标和屏幕可见性。

  • 仅与受信任的客户端一起使用。
  • 请注意，屏幕截图可能会捕获敏感数据。
  • 自动点击可能具有破坏性。

许可证

MIT许可证

相关 MCP