GNOME UI MCP

gnome-ui-mcp

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

它通过 AT-SPI 检查并操作 GNOME 桌面以发现元素，并通过 Mutter RemoteDesktop 输入。在实际使用中，这意味着可以查找和激活元素、输入文字、截取屏幕截图，以及使用等待助手来操作当前桌面会话。

导航采用快照驱动模式：先对活动窗口拍摄快照以获取稳定的元素 uid，然后对这些 uid 执行 click/fill/hover/fill_form。过期的 uid 会被拒绝，而不会被悄悄用于错误的目标；操作会自动等待 UI 稳定。请参阅下文的导航。

要求

• 使用 Wayland 的 GNOME Shell Linux 主机
• 要自动化的机器上有正在运行的本地 GNOME 会话
• 可用的会话环境：DBUS_SESSION_BUS_ADDRESS、XDG_RUNTIME_DIR、WAYLAND_DISPLAY、DISPLAY、XDG_SESSION_TYPE

Docker

• Docker Engine

容器必须在与 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

市场

仓库包含以下分发渠道的元数据：

• 通过 server.json 接入 MCP Registry
• 通过 .claude-plugin/plugin.json 接入 Claude Code 插件市场
• 通过 .github/plugin/plugin.json 接入 VS Code 和 GitHub Agent 插件市场

Claude Code 插件市场

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

/plugin marketplace add asattelmaier/gnome-ui-mcp

然后安装插件：

/plugin install gnome-ui-mcp

该插件通过 scripts/run-docker-mcp.sh 启动已发布的 Docker 镜像，因此主机必须能够使用 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 — 捕获活动窗口（或传入 list_windows 返回的 window，或传入 app_name）。每个元素都会获得一个稳定的不透明 uid，例如 7_42。
2. click / fill / hover / fill_form — 通过 uid 引用元素。操作会自动等待 Shell 稳定，并报告效果验证结果。传入 include_snapshot=true，即可在同一轮中获取结果的新快照。
3. select_window 用于设置隐式快照范围。

uid 仅对最新快照有效：如果 UI 已发生变化且某个 uid 因过期而被拒绝，请再次调用 take_snapshot 并使用新的 uid。较底层的路径工具（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 会话总线通信。