screen-mcp

<div align="center"> # 屏幕控制插件 [](https://deepwiki.com/88plug/screen-mcp) 给模型一双眼睛和手，让它能在 Linux Wayland 桌面上截图、点击、输入、滚动、拖拽，并读取任何可见的应用。 [](https://github.com/88plug/screen-mcp/actions/workflows/plugin-validate.yml) [](LICENSE.md) [](https://github.com/88plug/claude-code-plugins) [](https://88plug.github.io/screen-mcp/) </div> 屏幕控制插件是 Claude Code 的 MCP 服务器，允许模型看到和操作您的 GNOME/Wayland 桌面。它通过 PipeWire 捕获任何监视器，通过 `xdg-desktop-portal` RemoteDesktop 门户驱动指针和键盘，并且可选地使用 OCR 读取屏幕并使用 OmniParser ONNX 模型定位图标。它适用于希望拥有一个可以使用真实桌面应用程序的代理的开发人员，而不仅仅是一个浏览器。它纯粹是 Python 编写的，并且仅使用 CPU 运行。 ## 快速入门 在 Claude Code 中安装插件： ```text /plugin marketplace add 88plug/screen-mcp /plugin install screen-mcp@screen-mcp ``` 然后运行一次性依赖设置（服务器具有系统和 Python 依赖，清单无法为您安装）： ```bash # 在已安装的插件目录（或克隆）中 python3 -m venv .venv && .venv/bin/pip install -r requirements.txt ``` 首次使用时，桌面门户会弹出一个同意对话框，询问要共享哪个监视器（或哪些监视器）。选择一个，然后让模型截取屏幕截图： ```text 截取我的桌面屏幕截图，并告诉我哪个窗口是聚焦的。 ``` 您应该在几秒钟内收到带有标签的截图和聚焦窗口的名称。门户返回一个恢复令牌，缓存在 `~/.config/mcp-screen` 中，因此后续运行是无声的。 > [!IMPORTANT] > screen-mcp 仅在 Linux + Wayland + GNOME 上运行，并且出于设计考虑，定位仅限于 CPU。安装前请查看[需求](#需求)。 ## 功能 服务器将一个捕获和操作循环转换为 MCP 工具，模型可以直接调用： - 截取任何监视器或区域的屏幕截图，带有编号的标记叠加层和点击坐标。 - 在任何可见的应用程序中点击、输入、滚动和拖拽，包括原生 Wayland 应用程序，`xdotool` 和 XTEST 无法触及。 - 使用 OCR（RapidOCR）读取屏幕上的文本，并使用 OmniParser ONNX 模型（两者均为可选）定位图标。 - 感知变化：环境层通过帧差分来检测代理何时打开或操作失败。 - 缓存学习屏幕：写穿世界模型允许识别的屏幕在下次访问时跳过 OCR。 - 门控破坏性操作：选择加入确认门控阻止关闭组合键和破坏性关键字点击，直到调用者传递确认令牌。 它还附带一个 `drive-screen` 技能，该技能编码了定位 → 定位 → 操作 → 确认循环，以便模型可以开箱即用地使用工具。 ## 原则 — 代理誓言 屏幕控制插件是[代理誓言](https://theagentoath.com)的参考执行者：用户接管守护程序在人类移动鼠标时（`STOPPED` 结果）交出控制权，让人类控制自己的桌面。这是 §2（人类代理）和 §11（人类监督）可执行 - *不要与人类争夺鼠标。* 选择加入确认门控（§7，不要绕过安全）和每个操作的屏幕可见性（§5，透明度）完善了它。 ## MCP 工具 服务器公开以下工具。每个操作也接受 `space`（`view` / `desktop` / `norm`，默认为 `view` — 坐标如上次截图中看到的那样），`shot: true` 返回截图后，`verify: true` 警告操作未改变，`force: true` 绕过用户接管守护程序，和 `element: <id>` 点击上次注释截图中的元素 ID。 | 工具 | 功能 | |---|---| | `screen_screenshot` | 捕获桌面。`region` / `monitor` 缩放，`annotate=true` 标记编号，`use_cache=true` 重用学习元素，`fresh=true` 在静态监视器上强制当前帧。 | | `screen_list_monitors` | 监视器（原点/大小/缩放），桌面边界，聚焦窗口。 | | `screen_move_mouse` | 将指针移动到 `x,y`。 | | `screen_click` | 点击 `x,y` 或就地。`button`，`double`。 | | `screen_scroll` | 按方向和数量滚动。 | | `screen_drag` | 从一个点拖拽到另一个点。 | | `screen_key` | 按下按键或组合键，例如 `Ctrl+L`，`Enter`，`Alt+Tab`。 | | `screen_type` | 在聚焦窗口中输入文本（Unicode 通过剪贴板粘贴，ASCII 通过键码）。 | | `screen_focus` | 通过应用程序/标题/ID 提升并给予窗口键盘焦点。 | | `screen_do` | 运行一批有序操作。 | | `screen_tour` | 访问多个 UI 状态，返回每个状态的带标签的缩略图。 | | `screen_read_page` | 自动滚动可滚动视图并累积每个可交互元素。 | | `screen_wait` | 等待屏幕稳定，然后可选地截图。 | | `screen_session` | 记录器：`start` / `stop` / `list` / `status` / `replay-path`。 | | `screen_reload` | 在编辑后热重载服务器。 | | `screen_diag` | 健康转储：会话，指针，定位后端，世界模型统计。 | ## 需求 > [!IMPORTANT] > screen-mcp 针对特定堆栈。 它不会在其他地方运行。 - Linux + Wayland + GNOME。感知层使用捆绑的 GNOME Shell 扩展；AT-SPI 是 GTK 应用程序的备用方案。 - Python 3.10+（测试到 3.14）。 - GStreamer >= 1.28（使用 `leaky-type`；较旧的 `drop=` 在 1.28 中被删除）。 - PipeWire 和 `xdg-desktop-portal-gnome`。 - `wl-clipboard` 用于 `screen_type` 中的 Unicode 粘贴路径。 - 用于 Set-of-Marks 标签的 DejaVu Sans Bold 字体（默认为 PIL 默认字体）。 定位设计为仅限 CPU：服务器硬禁用 GPU（`CUDA_VISIBLE_DEVICES=""`）以获得可预测的延迟和无驱动程序故障。 <details> <summary>系统软件包</summary> 在 Python 依赖项之前安装系统依赖项。有关完整的 `pacman` / `apt` 一行命令，请参见 [requirements.txt](requirements.txt)。 ```bash # Arch / Manjaro sudo pacman -S python-gobject gobject-introspection \ gstreamer gst-plugins-base gst-plugins-good gst-libav \ pipewire pipewire-pulse xdg-desktop-portal-gnome \ wl-clipboard ttf-dejavu # Python 依赖项 pip install -r requirements.txt ``` </details> <details> <summary>GNOME Shell 扩展（推荐）</summary> 捆绑的 `window-info` 扩展为感知层提供可靠的聚焦窗口和窗口列表数据，并让 `screen_focus` 直接激活窗口。安装它需要一次性 Wayland 重新登录。 ```bash gnome-shell-extension/window-info@local/install.sh gnome-extensions enable window-info@local ``` </details> <details> <summary>内核输入后端（可选）</summary> 对于内核输入后端，通过将您的用户添加到 `input` 组来授予对 `/dev/uinput` 的访问权限。启动器（`bin/screen-mcp`）如果缺少所需依赖项，则会带有清晰的消息失败，因此配置错误的安装永远不会默默地半工作。 </details> ## 手动 MCP 设置 如果您不使用插件，请直接连接服务器。在 `~/.claude.json` 中的 `mcpServers` 下添加： ```json { "screen": { "command": "python3", "args": ["/path/to/screen-mcp/server.py"] } } ``` ## 配置 屏幕控制插件读取可选的环境变量。以下是一些常见的变量： - `MCP_SCREEN_GUARD=1` — 启用确认门控。破坏性组合键（`Ctrl+W`，`Alt+F4`），OCR 匹配的破坏性关键词和非允许列表操作在调用者传递 `ack=<reason>` 之前被阻止。 - `MCP_SCREEN_APPS="firefox,terminal"` — 启用门控时，限制操作到此允许列表中的聚焦应用程序。 - `MCP_SCREEN_AMBIENT=0` — 禁用环境 `SENSE` 提示块。 - `MCP_SCREEN_CPU_THREADS=6` — OmniParser 的 ONNX 内部操作线程数。 - `MCP_SCREEN_MAX_EDGE=2576` — 截图缩减目标（长边）。 <details> <summary>所有环境变量和数据路径</summary> | 变量 | 效果 | |---|---| | `MCP_SCREEN_GUARD=1` | 启用可靠性确认门控（破坏性组合键/关键词/非允许列表操作在 `ack` 之前被阻止）。 | | `MCP_SCREEN_APPS` | 启用门控时，允许列表中的聚焦应用程序。 | | `MCP_SCREEN_AUDIT_FRAMES=1` | 为每个审计行添加前后帧哈希和 `changed_bbox`（~100-500ms per 操作）。 | | `MCP_SCREEN_AMBIENT=0` | 禁用环境 `SENSE` 提示块。 | | `MCP_SCREEN_GUARD_PX=40` | 用户接管守护程序的阈值（实时指针与上一个命令指针）。 | | `MCP_SCREEN_CPU_THREADS=6` | OmniParser 的 ONNX 内部操作线程数。 | | `MCP_SCREEN_MAX_EDGE=2576` | 截图缩减目标（长边）。 | | `MCP_SCREEN_NO_FRESH=1` | 禁用静态监视器上的强制新鲜帧捕获。 | | `MCP_SCREEN_FOCUS_SETTLE_MS=150` | `screen_focus` 激活窗口后的延迟。 | | `MCP_SCREEN_NO_NUDGE=1` | 禁用指针损伤微调以启动静态监视器的帧。 | | 路径 | 内容 | |---|---| | `~/.config/mcp-screen/token` | 门户恢复令牌（一次性同意）。 | | `~/.local/share/mcp-screen/world/map.db` | 世界模型缓存（每个屏幕学习的元素）。 | | `~/.local/share/mcp-screen/sessions/<sid>/` | 记录器轨迹，帧，`replay.html`。 | | `~/.local/state/mcp-screen/actions.jsonl` | 可靠性审计日志（每个操作一行 JSON）。 | | `/tmp/screen_err.txt` | 最后一个未处理的工具跟踪栈（开发人员诊断）。 | </details> ## 开发 ```bash pytest -q # 测试在没有实时 D-Bus 的情况下运行（conftest 存根） ``` 编辑一个 `.py` 文件，然后在运行会话中调用 `screen_reload` 以在保留 MCP 连接的情况下重新执行服务器。对任何工具异常，调度器都会将完整的跟踪栈写入 `/tmp/screen_err.txt`；在调试崩溃时读取它。 ## 贡献 欢迎提出问题和拉取请求。请在打开 PR 之前运行 `pytest -q`。有关架构说明和捕获和输入层背后的操作细节，请参见 [CLAUDE.md](CLAUDE.md)。 ## 许可证 [FSL-1.1-ALv2](LICENSE.md) © 2026 [88plug](https://github.com/88plug)。功能源许可证在每个版本发布两年后转换为 Apache 2.0。