desktop-mcp

面向大语言模型的桌面视觉与控制，支持 Linux，包括 Wayland —— 模型截取整个屏幕的截图，然后在所看到的内容上点击、输入和滚动。基于 stdio 的纯 MCP，因此它可以在 Claude Code、Claude Desktop、Cursor 或任何其他 MCP 客户端中使用。

先读这里：你可能不需要这个

Anthropic 原生提供 computer use 功能，在它能工作的地方你应该改用这个功能——它集成得更好，而且确实在维护：

• macOS 和 Windows：Claude Desktop 在 Cowork 和 Claude Code 中内置了 computer use。它可以操控你的真实桌面。 (文档)

• 构建你自己的智能体：Claude API 有一个第一方的 computer 工具 （GA 版本为 computer_toolset_20260801 工具集）。 (文档)

这个项目填补的空白是 Linux。 截至 2026 年 8 月，computer use 在 Linux 桌面应用中尚不可用，而且 Wayland 上的桌面自动化确实很别扭，这是 X11 从未有过的：

• COSMIC 的合成器没有实现 wlr-screencopy，所以 grim 直接失败，每个截图工具都需要针对每个合成器的路径。

• 没有协议可以查询光标位置，也没有协议可以枚举其他客户端的窗口。

• 输入必须通过 /dev/uinput 从合成器下方注入，因为通常打包的 ydotool 暴露的是 相对 指针，其长距离跳转会被指针加速搞乱。

如果你在 macOS 或 Windows 上，这个仓库基本上是多余的。如果你在 Linux 上——尤其是 Wayland——它是可用的选择。

桌面自动化 MCP 服务器并不是一个新类别；已经有成千上万个 MCP 服务器。这里的特殊之处在于 Wayland 原生的绝对 uinput 输入路径，在 COSMIC 上实测像素级精确。

Related MCP server: mcp-linux-desktop

状态

编写时考虑了跨平台，但实际只有一种配置被验证过。其余只是代码路径，不是实证——请相应看待。

测试了什么，以及如何测试

在以下环境进行了端到端验证：

• Pop!_OS 24.04 LTS，内核 7.0.11，COSMIC（cosmic-comp 1.0.0），Wayland，单台 2560x1440 显示器，Python 3.13。

结果：

未测试但值得了解：多显示器布局、HiDPI 缩放、原始键码路径上的非美式键盘布局（wtype 能正确处理这些；uinput 键码假定为美式），以及所有非 COSMIC 合成器。

欢迎来自其他平台的报告——desktop_info 会输出诊断后端问题所需的一切信息。

安装

git clone <this repo> && cd desktop-mcp
uv venv && uv pip install -e .

macOS、Windows 和 Linux/X11 还需要输入依赖：

uv pip install -e ".[gui]"

Linux：一次性权限设置

在 Wayland 上注入输入意味着要写入 /dev/uinput，而它默认归 root 所有：

bash scripts/setup-linux.sh   # needs sudo once
# then log out and back in

macOS：一次性权限设置

在“系统设置 → 隐私与安全性”中，为启动服务器的应用（Terminal、iTerm、Claude Desktop）授予屏幕录制和辅助功能权限。

接入

Claude Code：

claude mcp add desktop -- /absolute/path/to/desktop-mcp/.venv/bin/python -m desktop_mcp.server

Claude Desktop（claude_desktop_config.json）和 Cursor（.cursor/mcp.json）使用相同的结构：

{
  "mcpServers": {
    "desktop": {
      "command": "/absolute/path/to/desktop-mcp/.venv/bin/python",
      "args": ["-m", "desktop_mcp.server"]
    }
  }
}

工具

坐标

截图在发送前会被缩小（默认长边 1400px），因此模型使用的是图像像素；服务器在每次调用时将它们映射回屏幕像素。请直接传入你从截图上读到的坐标。

这是大多数自制的 computer use 工具最容易搞错的细节。忽略它，每次点击都会落在目标位置的一个固定比例处。

为什么在 Linux 上使用 /dev/uinput 而不是 ydotool

通常打包的 ydotool 构建暴露的是 相对 指针，因此跳到 (1280, 720) 会被当作一次大的相对运动传递——合成器会对其应用指针加速。光标会落在目标附近而不是目标上，误差随距离增大。绝对 uinput 设备绕开了加速：在 2560x1440 屏幕上实测 5/5 精确。当 /dev/uinput 不可写时，ydotool 仍作为后备方案。

点击时序

合成器异步分发指针移动，而工具包会忽略在它们处理完将光标移到控件上的移动事件之前到达的按钮按下事件。在 COSMIC 上实测：移动和按下之间间隔 30ms 能可靠地高亮按钮，但绝不会激活它——悬停状态证明坐标是正确的，这使得这个失败很容易被误读为定位 bug。250ms 可以激活它。按下还必须保持（约 90ms）才能被识别为真正的点击，而不是一个杂散事件。

这两个延迟都可调；只有在你的桌面环境能承受时才降低它们。

安全

这赋予了模型与坐在机器前的人相同的操作权限。它可以读取屏幕上的任何内容——打开的密码管理器、私密消息、令牌——并点击任何东西，包括破坏性按钮。请将会话视为你把键盘交给了别人。

环境变量：

ctrl+alt+F1–F12 始终被阻止；VT 切换可能会让图形会话从你手中溜走。

一个只读审查者配置：

DESKTOP_MCP_READ_ONLY=1 python -m desktop_mcp.server

验证

.venv/bin/python scripts/mcp_smoke.py   # real stdio MCP round trip