glovebox-mcp

glovebox-mcp

沙盒化计算机操作 MCP 服务——让 AI Agent 操控真实浏览器和桌面应用 （鼠标、键盘、截图、视觉定位），并将其限制在嵌套 X11 窗口中，确保它永远无法触及你的真实屏幕、文件或其他应用。

就像实验室里的手套箱：Agent 伸手进入其中，操作真实应用，与其他一切隔绝。启动沙盒，在该窗口内登录你想要自动化的站点或应用，Agent 便只会在其中操作——你可以实时观看，并立即关闭它。

使用 Model Context Protocol，因此可与 Claude Code 等 MCP 客户端配合使用。你的主机可以运行 Wayland；沙盒会为 Agent 提供可操控的真实 X server。

_{Agent 在沙盒中操控真实浏览器——平滑移动光标、输入 Unicode 名称（Nadja Kovačič）、打字并提交。所有操作都限制在嵌套 X11 窗口中。}

为什么要使用嵌套 X11 沙盒？

• 大多数桌面自动化工具（xdotool、PyAutoGUI）仅支持 X11，但许多现代桌面运行的是 Wayland。
• Xephyr 在单个窗口内提供真实的 X server（DISPLAY :1）。Agent 的所有操作——点击、打字、截图——都限制在该窗口内，不会影响你的真实桌面。
• 你始终掌控一切：实时观看，运行 pkill Xephyr 即可关闭所有内容。

要求

• Linux——沙盒会嵌套一个真实的 X server（Xephyr），因此即使主机运行 Wayland，也能正常工作（通过 Xwayland）。不支持 macOS/Windows。项目在 Ubuntu 上开发；任何安装了下列软件包的现代 Linux 均可使用。
• Python 3.10+ 和 uv（用于创建虚拟环境）。
• 系统软件包——xserver-xephyr（Xephyr）、openbox、scrot、x11-utils、xdotool、 wmctrl、xclip（basic 模式还需要 tesseract-ocr）。在 Debian/Ubuntu 上，安装程序会通过 apt（sudo）自动安装这些软件包；在 Fedora/Arch 上，它会显示相应的 dnf/pacman 命令。MCP 服务本身与发行版无关——任何安装了这些工具的 Linux 均可使用。
• 沙盒中需要一个浏览器（Chromium 或 Chrome）。
• NVIDIA GPU（≥6 GB VRAM）——仅 local 视觉模式需要。

安装

选择一种视觉后端并运行对应的一行命令（克隆 → 安装）。每个命令都会安装系统软件包（在 Debian/Ubuntu 上通过 apt 自动安装）和该模式所需的 Python 依赖，并生成路径已填写、可直接粘贴的 mcp-config.json。

none——不使用本地模型；由 Agent 自行读取截图（最轻量，启动即用）：

git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh none

basic——使用 Tesseract OCR 进行定位（parse_screen → 文本 + 坐标，仅使用 CPU）：

git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh basic

local——在 NVIDIA GPU 上运行 OmniParser（parse_screen → 文本 + 图标，像素级精确；权重约 4 GB，≥6 GB VRAM）：

git clone https://github.com/segentic-lab/glovebox-mcp && cd glovebox-mcp && ./install.sh local

你的选择会写入 .vision-mode（可通过 GLOVEBOX_VISION 环境变量逐次运行时覆盖）。

兼容任何 MCP 客户端 / 执行框架

Claude Code、Cursor、Codex 或你自己的 Agent 都可以使用——这是一个标准 MCP 服务，不依赖任何特定宿主。 有两点兼容性说明：basic/local 会将元素坐标作为文本返回，因此纯文本 Agent 也能使用；none 依赖客户端将工具的截图传递给多模态模型（适用于 Claude Code、Cursor 及其他支持图像的 MCP 客户端）。

快速开始

1. 启动沙盒（保持运行）：

   ./start-display.sh              # 1440×900 Xephyr window with a browser
   ./start-display.sh 1920x1080    # …or pass a screen size (or set $RES)
   

   在该窗口内登录你想要自动化的任意站点或应用。
2. 向 MCP 客户端注册服务。install.sh 已将包含实际安装路径的 mcp-config.json 写入磁盘——将其中的 glovebox 配置块复制到客户端的 MCP 配置中：

   { "mcpServers": { "glovebox": {
       "command": "/abs/path/to/glovebox-mcp/.venv/bin/python",   // filled in by install.sh
       "args":    ["/abs/path/to/glovebox-mcp/server.py"],
       "env":     { "DISPLAY": ":1" }
   } } }
   

   重启客户端，使其加载该服务。
3. 让 Agent 截图 / 点击 / 打字——它只会操作 :1 窗口。

使用 AI Agent 操控？ 将 AGENTS.md 粘贴到 Agent 的系统提示词中——其中介绍了观察 → 操作 → 验证的循环、定位方法、上传/Unicode 的注意事项，以及何时停止。

工具

工具	说明
status()	通过一次只读调用获取服务 + 沙盒状态：版本、视觉后端、主机显示、运行中的实例，以及已安装的系统依赖（xdotool、xclip、Xephyr、tesseract、OmniParser 权重）。请先运行，并将结果粘贴到错误报告中。
parse_screen()	视觉定位 → 检测到的元素 JSON（id、类型、标签、是否可交互、像素中心点；每次最多 300 个，通过 "truncated" 标记是否截断）+ /tmp/glovebox_annotated_<N>.png 中带编号的 Set-of-Mark 图像。（local 模式：在 GPU 上运行 OmniParser，约 2 秒。）
click_element(id)	点击上次 parse_screen 检测到的元素（无需猜测坐标）。
screenshot()	截取某个实例的屏幕。
click(x,y) · move_mouse · scroll · drag · double_click	指针操作。
type_text(text)	安全输入 Unicode（ASCII 字符通过 xdotool 输入；包含 č/š/ž… 的内容通过剪贴板插入，因为部分 GTK 应用会静默丢弃 xdotool 合成的 Unicode 字符）。
press_keys("ctrl+a"/"Return"/…)	按键/组合键（xdotool 语法）。
upload_file(filepath, selector?)	通过 Chrome DevTools Protocol 将本地文件附加到页面的 <input type=file>。嵌套的 X11 文件选择器对自动化不可见，且会挂起渲染器，因此所有上传都应使用此工具——切勿点击上传按钮并期待弹出对话框。适用于由 launch_app/start-display.sh 启动的 Chromium（它们会打开每个实例专用的 --remote-debugging-port，端口为 9222+N）。仅适用于浏览器文件输入框——原生应用请参阅 open_file。
open_file(filepath, app?)	在实例的显示器上用原生应用打开本地文件（例如 app="gimp"），或通过 xdg-open 打开。GTK 应用会采用与 launch_app 相同的 X11/D-Bus 处理方式。
list_files()	列出实例的暂存文件夹 files/<N>/（位于安装目录下）及其内容。
launch_app(command, name?, size?) · list_instances() · close_instance(n)	多实例控制（见下文）。
wait_ms(ms) · get_screen_size()	计时 / 沙盒大小。

每个控制工具都接受 instance=N，以及可选的 observe / settle_ms（见下文）。 在 local 模式下，OmniParser 会在首次调用 parse_screen 时延迟加载（首次约 6 秒，之后每次解析约 2 秒）。

结构化且如实的响应

每个工具都会返回 JSON：{"ok": true, "action": "click", "instance": 1, "detail": "clicked (10,20) button 1", …}。 失败时会设置 MCP isError 标记，并在错误文本中嵌入相同格式的 JSON——{"ok": false, "error": "…", "fix": "…"}——其中 fix 指明解除阻塞所需的调用 （例如，点击已失效的实例时会提示运行 list_instances() / launch_app()；元素 id 未知时会提示重新运行 parse_screen()）。静默无操作也会被视为失败：无效的 keysym、滚动距离为零、关闭未运行的实例，或未安装 xclip 时输入非 ASCII 字符，都会返回错误，而不会假装成功。screenshot() 返回 PNG 图像；observe="screenshot"|"parse" 可在一次调用中返回 [json, image]。

视觉后端（可选）

GLOVEBOX_VISION 环境变量、.vision-mode 文件或默认值 local：

模式	parse_screen	依赖	适用场景
none	已禁用（返回说明）——使用 screenshot() + reason	无（mcp、mss、xdotool）	最轻量；由 Agent 自身视觉进行定位
basic	Tesseract OCR → 文本元素 + 坐标	tesseract-ocr + pytesseract	无需 GPU；仅进行文本定位
local	OmniParser → 文本和图标 + 坐标	torch + CUDA + OmniParser 权重	定位效果最佳

随时使用 ./install.sh <mode> 切换（只安装该模式所需的依赖）。

多实例（应用窗口集群）

每个控制工具都接受 instance=N（默认值 1 = start-display.sh 沙盒）。可以启动更多实例 — 每个实例都会在主机桌面上拥有自己的 Xephyr 显示和窗口：

• launch_app(command, name?, size?) → 在下一个空闲的 :N 上启动任意 GUI 应用 （chromium、gimp、inkscape、xterm 等）。Chromium 会自动获取 X11 标志、专属实例配置文件、 远程调试端口和 D-Bus 隔离。返回实例 ID。
• list_instances() · close_instance(n)。

由于每个显示都有自己的光标，多个 Agent 可以并行操控不同实例 — 每个 Agent 控制一个窗口。唯一共享的资源是 local 模式下 parse_screen 使用的 GPU（请求只会排队）。 新窗口所在的主机显示由 GLOVEBOX_HOST_DISPLAY 指定（默认值 :0）；XAUTHORITY 会自动发现。

单次调用即可操作并观察

click · click_element · type_text · press_keys · scroll · drag · double_click 接受 observe（默认值 none · screenshot · parse）和 settle_ms。使用 observe="screenshot" 时，操作调用会同时返回结果和操作后的屏幕（并通过 settle_ms 等待页面先完成更新） — 无需单独再调用一次截图。默认的 none 可让常规步骤保持轻量；对于会更改页面的步骤（导航、提交）， 可选择 screenshot/parse。

文件与上传

每个实例都会在安装目录中获得一个暂存文件夹 files/<N>/ — 这是该实例的固定文件存放位置 （原生应用可以读取；由于目录位于 $HOME 下，snap Chromium 也可以读取）。 list_files(instance) 会显示该文件夹及其内容。

• 浏览器 <input type=file> → 使用 upload_file(path, instance)（通过 CDP）。嵌套的文件 选择器对自动化不可见，而且会导致 snap Chromium 挂起，因此切勿点击上传按钮并等待对话框。
• 原生应用（GIMP、Inkscape、编辑器）→ 使用 open_file(path, instance, app="gimp")，或直接 操作应用自己的打开对话框 — 与浏览器的文件选择器不同，它是一个真正可见的窗口，你可以在其中输入 路径（在 GTK 文件选择器中按 Ctrl+L）。
• 保存／下载 → 应用以你的用户身份运行，因此可以保存到你有写入权限的任何位置。launch_app 启动的 Chromium 实例已预先配置为将内容下载并“另存为”到 files/<N>/；也可将原生应用的 “保存”对话框指向该目录，然后通过 list_files(instance) 查看结果。

维护（local 模式）

install.sh 会克隆 OmniParser、下载 v2 权重，并自动 应用两个补丁：

• 将 PaddleOCR 设为可选（这里使用 easyocr）：OmniParser/util/utils.py 中的 from paddleocr import PaddleOCR 会用 try/except 包裹，模块级别的 paddle_ocr = PaddleOCR(...) 则会加上保护：… if PaddleOCR is not None else None。
• 将 transformers 固定到 4.49.0 — 更新版本会破坏 Florence-2 的远程配置。

如果你手动升级 OmniParser，请重新应用 PaddleOCR 补丁。权重位于 OmniParser/weights/。

停止

pkill Xephyr      # closes the sandbox (browser + WM + display)

安全

• Agent 的输入和视觉范围仅限于沙盒显示 — 它看不到也无法控制你的真实桌面。
• 服务端进程以你的用户身份运行（可访问 Shell 和文件，与其他 MCP 服务一样）；只有它的GUI 控制 被限制在 Xephyr 窗口内。若要在操作系统层面隔离你的文件，请在 VM 或容器中运行。
• 你可以实时查看所有操作，也可以随时通过 pkill Xephyr 立即关闭。
• 请负责任地进行自动化操作 — 仅限使用你获授权访问的网站和服务。

文件

• server.py — MCP 服务（包含所有工具）。
• install.sh — 根据模式安装（none / basic / local）。
• start-display.sh — 启动 Xephyr 沙盒（显示 + 窗口管理器 + 浏览器）。
• AGENTS.md — 可直接提供给 AI Agent 的工具使用说明（粘贴到其系统提示词中）。
• mcp-config.json — 可直接粘贴的 MCP 客户端配置片段。

致谢

local 视觉模式使用 Microsoft 的 OmniParser （由 install.sh 克隆并下载权重，遵循其自身许可证）。屏幕捕获使用 mss；输入由 xdotool 驱动。与 Microsoft 无关联。

贡献

本项目按 原样 以 MIT 许可证发布。欢迎提交问题和 PR，但本项目由一人维护—— 不保证提供支持或响应时间。 如果它对你有用，点个 ⭐ 就是很好的支持。

许可证

MIT——请参阅 LICENSE。