AI导哈

GNOME桌面自动化服务器

一个用于GNOME Wayland桌面的小型MCP服务器，提供桌面元素查找、激活、输入、截图等功能，支持通过Docker运行。

  • by asattelmaier
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 asattelmaier/gnome-ui-mcp

使用说明

侏儒ui mcp

用于GNOME Wayland桌面自动化的小型MCP服务器。

它通过AT-SPI进行发现，并通过Mutter RemoteDesktop进行输入，从而公开GNOME桌面检查和交互。在实践中，这意味着当前桌面会话的元素查找、激活、键入、屏幕截图和等待助手。

对于导航，它遵循快照驱动模型：对活动窗口进行快照以获取稳定的元素uid，然后 click/fill/hover/fill_form 那些uid。过时的用户界面会被拒绝，而不是默默地被错误定位，操作会自动等待用户界面稳定。看 导航 在......下面

需求

  • Wayland上带有GNOME Shell的Linux主机
  • 要自动化的计算机上的实时本地GNOME会话
  • 可用会话环境： DBUS_SESSION_BUS_ADDRESS, XDG_RUNTIME_DIR, WAYLAND_DISPLAY, DISPLAY, XDG_SESSION_TYPE

码头工人

  • Docker引擎

容器必须与GNOME会话在同一台机器上运行，并使用会话环境和运行时挂载。

Docker镜像

建议通过已发布的GHCR映像运行服务器：

ghcr.io/asattelmaier/gnome-ui-mcp:latest

latest 追踪最新版本。版本标签，例如 v0.1.0 同时发布匹配的图像标签。

Docker设置

直接的 docker run:

docker run --rm \
  --security-opt apparmor=unconfined \
  --network host \
  --user "$(id -u):$(id -g)" \
  -e DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" \
  -e XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" \
  -e WAYLAND_DISPLAY="$WAYLAND_DISPLAY" \
  -e DISPLAY="$DISPLAY" \
  -e XDG_SESSION_TYPE="${XDG_SESSION_TYPE:-wayland}" \
  -v "$XDG_RUNTIME_DIR:$XDG_RUNTIME_DIR" \
  -v /tmp/.X11-unix:/tmp/.X11-unix:ro \
  ghcr.io/asattelmaier/gnome-ui-mcp:latest

--user "$(id -u):$(id -g)" 是必需的，因此容器将加入同一用户 会话为GNOME、D-Bus和AT-SPI。

通过Compose进行本地开发：

此路径还需要 docker compose.

  1. 复制 .env.example 到 .env
  2. 根据会话调整值
  3. 运行：
docker compose build
docker compose run --rm gnome-ui-mcp

可用运输工具

服务器支持本地和Docker中的三种传输方式：

  • stdio （默认）：建议用于生成服务器进程的本地MCP客户端
  • streamable-http：建议用于基于HTTP的集成 http://127.0.0.1:8000/mcp
  • sse：可用于向后兼容 http://127.0.0.1:8000/sse 通过消息POST发送至 http://127.0.0.1:8000/messages/

示例：

gnome-ui-mcp
gnome-ui-mcp --transport streamable-http
gnome-ui-mcp --transport sse

通过在镜像名称后附加相同的标志，可以将它们传递给Docker镜像：

docker run ... ghcr.io/asattelmaier/gnome-ui-mcp:latest --transport streamable-http
docker run ... ghcr.io/asattelmaier/gnome-ui-mcp:latest --transport sse

市场

存储库包括这些分销渠道的元数据：

克劳德代码插件市场

要在Claude Code中将此存储库添加为插件市场：

/plugin marketplace add asattelmaier/gnome-ui-mcp

然后安装插件：

/plugin install gnome-ui-mcp

插件通过以下方式启动已发布的Docker镜像 scripts/run-docker-mcp.sh所以Docker和 GNOME会话环境必须在主机上可用。

MCP客户端配置示例

{
  "mcpServers": {
    "gnome-ui": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--security-opt",
        "apparmor=unconfined",
        "--network",
        "host",
        "--user",
        "1000:1000",
        "-e",
        "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus",
        "-e",
        "XDG_RUNTIME_DIR=/run/user/1000",
        "-e",
        "WAYLAND_DISPLAY=wayland-0",
        "-e",
        "DISPLAY=:0",
        "-e",
        "XDG_SESSION_TYPE=wayland",
        "-v",
        "/run/user/1000:/run/user/1000",
        "-v",
        "/tmp/.X11-unix:/tmp/.X11-unix:ro",
        "ghcr.io/asattelmaier/gnome-ui-mcp:latest"
      ]
    }
  }
}

导航

驱动桌面的幸运方式是快照优先：

  1. take_snapshot --捕获活动窗口（或传递 window 从 list_windows，或 app_name).每个元素都得到稳定的不透明 uid 例如 7_42.
  2. click / fill / hover / fill_form --参考元素 uid。操作会自动等待shell稳定并报告效果验证。通过 include_snapshot=true 以获得同一回合结果的最新快照。
  3. select_window 设置隐式快照作用域。

A. uid 仅对最新快照有效：如果UI发生更改，并且某个uid因过时而被拒绝，则调用 take_snapshot 再次使用新鲜的。基于路径的低级工具(find_elements, click_element, set_element_text，…）仍然可用作高级构建块。

工具类别可以在启动时启用或禁用 --category NAME / --no-category NAME （例如 --category navigation --category input).

API文档

完整的工具参考可在 https://asattelmaier.github.io/gnome-ui-mcp/

安全

此服务器可以检查和控制活动的桌面会话。仅与受信任的MCP客户端一起使用。 Ubuntu上的容器化执行可能需要 --security-opt apparmor=unconfined 因此该进程可以与GNOME会话总线通信。

相关 MCP