GNOME UI MCP server

gnome-ui-mcp

Small MCP server for GNOME Wayland desktop automation.

It 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.

For 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 below.

Requirements

• Linux host with GNOME Shell on Wayland
• Live local GNOME session on the machine you want to automate
• Session environment available: DBUSSESSIONBUSADDRESS, XDGRUNTIMEDIR, WAYLANDDISPLAY, DISPLAY, XDGSESSIONTYPE

Docker

• Docker Engine

The container must run on the same machine as the GNOME session and use the session environment plus runtime mounts.

Docker image

The recommended way to run the server is via the published GHCR image:

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

latest tracks the most recent release. Version tags such as v0.1.0 publish matching image tags as well.

Docker setup

Direct 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)" is required so the container joins the same user session as GNOME, D-Bus, and AT-SPI.

Local development via Compose:

This path additionally requires docker compose.

1. Copy .env.example to .env
2. Adjust the values to your session
3. Run:

docker compose build
docker compose run --rm gnome-ui-mcp

Available transports

The server supports three transports, both locally and in Docker:

• stdio (default): recommended for local MCP clients that spawn the server process
• streamable-http: recommended for HTTP-based integrations on http://127.0.0.1:8000/mcp
• sse: available for backwards compatibility on http://127.0.0.1:8000/sse with message POSTs to http://127.0.0.1:8000/messages/

Examples:

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

The same flags can be passed to the Docker image by appending them after the image name:

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

Marketplaces

The repository includes metadata for these distribution channels:

• MCP Registry via server.json
• Claude Code plugin marketplaces via .claude-plugin/plugin.json
• VS Code and GitHub agent plugin marketplaces via .github/plugin/plugin.json

Claude Code plugin marketplace

To add this repository as a plugin marketplace in Claude Code:

/plugin marketplace add asattelmaier/gnome-ui-mcp

Then install the plugin:

/plugin install gnome-ui-mcp

The plugin starts the published Docker image through scripts/run-docker-mcp.sh, so Docker and the GNOME session environment must be available on the host.

Example MCP client configuration

Shortened. The full README is on GitHub.