GNOME UI MCP

gnome-ui-mcp

GNOME Wayland デスクトップ自動化用の小規模な MCP サーバーです。

AT-SPI による検出と Mutter RemoteDesktop による入力を通じて、GNOME デスクトップの調査と操作を提供します。具体的には、現在のデスクトップセッションで要素の検索、アクティブ化、入力、スクリーンショットの取得、待機用ヘルパーを利用できます。

ナビゲーションには、スナップショット主導のモデルを採用しています。アクティブウィンドウのスナップショットを取得して安定した要素 uid を得た後、それらの uid に対して click／fill／hover／fill_form を実行します。古くなった uid は、対象を誤って操作することなく拒否されます。また、操作後は UI が落ち着くまで自動的に待機します。詳しくは、以下のナビゲーションをご覧ください。

要件

• GNOME Shell を Wayland 上で実行している 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 でも、次の 3 種類のトランスポートをサポートしています。

• stdio（デフォルト）：サーバープロセスを起動するローカル MCP クライアントに推奨
• streamable-http：http://127.0.0.1:8000/mcp での HTTP ベースの連携に推奨
• sse：後方互換性のために利用可能。http://127.0.0.1:8000/sse を使用し、メッセージは http://127.0.0.1:8000/messages/ に POST します

例：

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

マーケットプレイス

リポジトリには、次の配布チャネル向けのメタデータが含まれています。

• MCP Registry（server.json）
• Claude Code プラグインマーケットプレイス（.claude-plugin/plugin.json）
• VS Code および GitHub のエージェントプラグインマーケットプレイス（.github/plugin/plugin.json）

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 を指定することもできます）。各要素には 7_42 のような安定した不透明な uid が割り当てられます。
2. click／fill／hover／fill_form — uid で要素を指定します。操作後、シェルが落ち着くまで自動的に待機し、効果の検証結果を報告します。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 でコンテナー化して実行する場合、プロセスが GNOME セッションバスと通信できるように、--security-opt apparmor=unconfined が必要になることがあります。