{
  "markdown": "# gnome-ui-mcp\n\nSmall MCP server for GNOME Wayland desktop automation.\n\nIt exposes GNOME desktop inspection and interaction through AT-SPI for discovery and Mutter RemoteDesktop for input. In practice that means element lookup, activation, typing, screenshots, and wait helpers for the current desktop session.\n\nFor navigation it follows a snapshot-driven model: take a snapshot of the active window to get stable element uids, then `click`/`fill`/`hover`/`fill_form` those uids. Stale uids are rejected rather than silently mis-targeted, and actions auto-wait for the UI to settle. See [Navigation](#navigation) below.\n\n## Requirements\n\n- Linux host with GNOME Shell on Wayland\n- Live local GNOME session on the machine you want to automate\n- Session environment available: `DBUS_SESSION_BUS_ADDRESS`, `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`, `DISPLAY`, `XDG_SESSION_TYPE`\n\n### Docker\n\n- Docker Engine\n\nThe container must run on the same machine as the GNOME session and use the session environment plus runtime mounts.\n\n## Docker image\n\nThe recommended way to run the server is via the published GHCR image:\n\n```text\nghcr.io/asattelmaier/gnome-ui-mcp:latest\n```\n\n`latest` tracks the most recent release. Version tags such as `v0.1.0` publish matching image tags as well.\n\n## Docker setup\n\nDirect `docker run`:\n\n```bash\ndocker run --rm \\\n  --security-opt apparmor=unconfined \\\n  --network host \\\n  --user \"$(id -u):$(id -g)\" \\\n  -e DBUS_SESSION_BUS_ADDRESS=\"$DBUS_SESSION_BUS_ADDRESS\" \\\n  -e XDG_RUNTIME_DIR=\"$XDG_RUNTIME_DIR\" \\\n  -e WAYLAND_DISPLAY=\"$WAYLAND_DISPLAY\" \\\n  -e DISPLAY=\"$DISPLAY\" \\\n  -e XDG_SESSION_TYPE=\"${XDG_SESSION_TYPE:-wayland}\" \\\n  -v \"$XDG_RUNTIME_DIR:$XDG_RUNTIME_DIR\" \\\n  -v /tmp/.X11-unix:/tmp/.X11-unix:ro \\\n  ghcr.io/asattelmaier/gnome-ui-mcp:latest\n```\n\n`--user \"$(id -u):$(id -g)\"` is required so the container joins the same user\nsession as GNOME, D-Bus, and AT-SPI.\n\nLocal development via Compose:\n\nThis path additionally requires `docker compose`.\n\n1. Copy `.env.example` to `.env`\n2. Adjust the values to your session\n3. Run:\n\n```bash\ndocker compose build\ndocker compose run --rm gnome-ui-mcp\n```\n\n## Available transports\n\nThe server supports three transports, both locally and in Docker:\n\n- `stdio` (default): recommended for local MCP clients that spawn the server process\n- `streamable-http`: recommended for HTTP-based integrations on `http://127.0.0.1:8000/mcp`\n- `sse`: available for backwards compatibility on `http://127.0.0.1:8000/sse` with message POSTs to `http://127.0.0.1:8000/messages/`\n\nExamples:\n\n```bash\ngnome-ui-mcp\ngnome-ui-mcp --transport streamable-http\ngnome-ui-mcp --transport sse\n```\n\nThe same flags can be passed to the Docker image by appending them after the image name:\n\n```bash\ndocker run ... ghcr.io/asattelmaier/gnome-ui-mcp:latest --transport streamable-http\ndocker run ... ghcr.io/asattelmaier/gnome-ui-mcp:latest --transport sse\n```\n\n## Marketplaces\n\nThe repository includes metadata for these distribution channels:\n\n- MCP Registry via [`server.json`](server.json)\n- Claude Code plugin marketplaces via [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)\n- VS Code and GitHub agent plugin marketplaces via [`.github/plugin/plugin.json`](.github/plugin/plugin.json)\n\n### Claude Code plugin marketplace\n\nTo add this repository as a plugin marketplace in Claude Code:\n\n```sh\n/plugin marketplace add asattelmaier/gnome-ui-mcp\n```\n\nThen install the plugin:\n\n```sh\n/plugin install gnome-ui-mcp\n```\n\nThe plugin starts the published Docker image through\n[`scripts/run-docker-mcp.sh`](scripts/run-docker-mcp.sh), so Docker and the\nGNOME session environment must be available on the host.\n\n## Example MCP client configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"gnome-ui\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"--security-opt\",\n        \"apparmor=unconfined\",\n        \"--network\",\n        \"host\",\n        \"--user\",\n        \"1000:1000\",\n        \"-e\",\n        \"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus\",\n        \"-e\",\n        \"XDG_RUNTIME_DIR=/run/user/1000\",\n        \"-e\",\n        \"WAYLAND_DISPLAY=wayland-0\",\n        \"-e\",\n        \"DISPLAY=:0\",\n        \"-e\",\n        \"XDG_SESSION_TYPE=wayland\",\n        \"-v\",\n        \"/run/user/1000:/run/user/1000\",\n        \"-v\",\n        \"/tmp/.X11-unix:/tmp/.X11-unix:ro\",\n        \"ghcr.io/asattelmaier/gnome-ui-mcp:latest\"\n      ]\n    }\n  }\n}\n```\n\n## Navigation\n\nThe blessed way to drive the desktop is snapshot-first:\n\n1. `take_snapshot` — capture the active window (or pass `window` from `list_windows`, or `app_name`). Every element gets a stable opaque `uid` such as `7_42`.\n2. `click` / `fill` / `hover` / `fill_form` — reference elements by `uid`. Actions auto-wait for the shell to settle and report effect verification. Pass `include_snapshot=true` to get a fresh snapshot of the result in the same turn.\n3. `select_window` sets the implicit snapshot scope.\n\nA `uid` is only valid for the latest snapshot: if the UI changed and a uid is rejected as stale, call `take_snapshot` again and use a fresh one. The lower-level path-based tools (`find_elements`, `click_element`, `set_element_text`, …) remain available as advanced building blocks.\n\nTool categories can be enabled or disabled at startup with `--category NAME` / `--no-category NAME` (for example `--category navigation --category input`).\n\n## API Documentation\n\nComplete tool reference available at [https://asattelmaier.github.io/gnome-ui-mcp/](https://asattelmaier.github.io/gnome-ui-mcp/)\n\n## Security\n\nThis server can inspect and control the active desktop session. Use it only with trusted MCP clients.\nContainerized execution on Ubuntu may require `--security-opt apparmor=unconfined`\nso the process can talk to the GNOME session buses.\n",
  "bytes": 5767,
  "sha": "342ff5980f2f55b41608dda3a1e5eac17311e9481c30b53c09b6af4a4f1eb80e",
  "repo_slug": "asattelmaier/gnome-ui-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_asattelmaier_gnome_ui_mcp_5d7a68ef/readme"
}