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 = []

工具

核心能力

提示渲染工具

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

提示

配置和定制

环境变量

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

传递环境变量

您可以在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许可证