kwin-mcp

kwin-mcp

KDE Plasma 6 Wayland 上で Linux デスクトップ GUI を自動化するための Model Context Protocol サーバー

isac322/kwin-mcp の積極的にメンテナンスされているフォークです。このフォークには、ユーザーが待ち望んでいた修正が含まれています。MCP Python SDK 2.x への対応、仮想セッションでのテキスト入力（ホストのキーマップからの分離）、信頼性の高いウィンドウフォーカス、上限付き起動待機、入力が黙って破棄される問題の修正、正確なエラー契約などです。詳しくは変更履歴とリリースをご覧ください。インストール：uv tool install git+https://github.com/VibeProgramm/kwin-mcp

Model Context Protocol（MCP） サーバーです。AI エージェント（Claude Code、Cursor、その他の MCP クライアント）が、ユーザーのデスクトップに影響を与えることなく、完全に分離された仮想 KWin セッション内であらゆる Wayland アプリケーションを起動、操作、監視できます。また、既存の KWin セッション（実際のデスクトップまたはコンテナー）に接続して、ライブデスクトップの自動化を行うこともできます。マウス、キーボード、タッチ、クリップボード、アクセシビリティツリーの検査、スクリーンショットの撮影、ウィンドウ管理を網羅する 30 個の MCP ツールを備えた kwin-mcp は、Linux でのエンドツーエンド GUI テストとデスクトップ自動化に必要なすべてを提供します。

目次

• kwin-mcp を選ぶ理由
• ユースケース
• クイックスタート
• 設定
• 利用可能なツール
• 仕組み
• システム要件
• インストール
• 制限事項
• コントリビューション
• ライセンス

kwin-mcp を選ぶ理由

• 分離されたセッション -- 各セッションは、それぞれ独自の dbus-run-session + kwin_wayland --virtual サンドボックスで実行されます。ホストのデスクトップには一切影響しません。
• ライブセッションに対応 -- 実際の KDE Plasma デスクトップ、またはコンテナー内の KWin インスタンス（例：systemd-nspawn）に接続し、共同で「画面を共有」するワークフローを実現できます。
• 操作にスクリーンショットは不要 -- AT-SPI2 アクセシビリティツリーによって、AI エージェントに構造化されたウィジェットデータ（ロール、名前、座標、状態、利用可能なアクション）が提供されるため、視覚情報だけに頼らず UI 要素を操作できます。
• 認証プロンプトが不要 -- KWin のプライベートな EIS（Emulated Input Server）D-Bus インターフェースを直接使用し、XDG RemoteDesktop ポータルを迂回します。ユーザー確認ダイアログは表示されません。
• あらゆる Wayland アプリで動作 -- KDE Plasma 6 Wayland 上で動作するものであれば、Qt、GTK、Electron など、すべてに対応します。入力は標準の libei プロトコルを介して注入されます。
• 入力を包括的にカバー -- マウス、キーボード、マルチタッチ、クリップボードのすべてが分離されたセッション経由で注入され、デスクトップを完全に自動化できます。

ユースケース

GUI テストの自動化

ヘッドレスの分離セッション内で、KDE／Qt／GTK アプリケーションのエンドツーエンド GUI テストを実行できます。kwin-mcp は各アプリを専用の仮想 KWin コンポジターで起動し、マウス、キーボード、タッチ入力で操作した後、スクリーンショットとアクセシビリティツリーで結果を検証します。物理ディスプレイは不要です。

AI 駆動のデスクトップ自動化

Claude Code などの AI エージェントに、デスクトップアプリケーションを自律的に操作させることができます。エージェントはアクセシビリティツリーを読み取って UI を理解し、30 個の MCP ツールを使って操作を行い、スクリーンショットで結果を確認します。これにより、あらゆる Wayland アプリケーションで完全なフィードバックループを実現できます。

デスクトップでのライブコラボレーション

実際のデスクトップセッションに接続して、Claude が画面を確認し、操作できるようにします。session_connect を使用するか、--default-live-session を渡してライブモードをデフォルトに設定します。コンテナ内（例：systemd-nspawn）で実行中の KWin への接続にも対応しており、エージェント用のデスクトップを分離できます。

CI/CD でのヘッドレス GUI テスト

Linux デスクトップの GUI テストを CI/CD パイプラインに統合できます。kwin-mcp の仮想セッションには X11 や物理ディスプレイサーバーが不要なため、GitHub Actions や Linux 上の GitLab CI ランナーのようなヘッドレス環境に適しています。

キオスクと組み込みデバイスの自動化

KDE Plasma または KWin のみの Wayland コンポジターを実行するキオスクインターフェースや組み込み Linux デスクトップを自動化できます。session_start を使用してキオスク UI の分離された仮想テストを行うか、session_connect を使用してライブのキオスクまたは組み込みデバイスのセッションに直接接続し、リアルタイムの自動化や診断を行います。

クイックスタート

KDE Plasma 6 が Wayland 上で必要です。詳細はシステム要件をご覧ください。

1. インストール

# Using uv (recommended)
uv tool install git+https://github.com/VibeProgramm/kwin-mcp

# Or from a source checkout
git clone https://github.com/VibeProgramm/kwin-mcp.git
cd kwin-mcp
uv tool install .

2. Claude Code を設定

プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "kwin-mcp": {
      "command": "uvx",
      "args": ["kwin-mcp"]
    }
  }
}

3. 使用する

Claude Code に GUI アプリケーションの起動と操作を依頼します：

Start a KWin session, launch kcalc, and press the buttons to calculate 2 + 3.

Claude Code は自律的に分離されたセッションを開始し、アプリを起動して、アクセシビリティツリーを読み取ってボタンを見つけ、クリックし、結果を確認するためにスクリーンショットを撮影します。

設定

推奨：プラグインとしてインストール

kwin-mcp をエディターに最も手早く組み込む方法は、同梱のプラグインのいずれかをインストールすることです。各プラグインは MCP サーバーを自動登録し、エージェントにツールを呼び出すタイミング（セッションモードの選択、観察 → 操作 → 検証のループ、US-QWERTY と Unicode 入力の使い分け、AT-SPI2 の座標変換、その他のプラットフォーム固有の注意点）を教える kwin-desktop-automation スキルも含みます。

Claude Code — マーケットプレイスからプラグインをインストールします：

/plugin marketplace add VibeProgramm/kwin-mcp
/plugin install kwin-mcp@kwin-mcp

OpenCode — npm プラグインを opencode.json に追加します：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@isac322/kwin-mcp-opencode"]
}

統合ガイド全文（手動での代替設定、スキルのカスタマイズ、トラブルシューティング）については、docs/ai-agent-integration.mdをご覧ください。

Claude Code

プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "kwin-mcp": {
      "command": "uvx",
      "args": ["kwin-mcp"]
    }
  }
}

または、グローバルにインストールした場合：

{
  "mcpServers": {
    "kwin-mcp": {
      "command": "kwin-mcp"
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "kwin-mcp": {
      "command": "uvx",
      "args": ["kwin-mcp"]
    }
  }
}

直接実行

# As an installed script
kwin-mcp

# As a Python module
python -m kwin_mcp

# Interactive CLI (REPL for rapid testing)
kwin-mcp-cli

# Live session mode (default to real desktop instead of virtual)
kwin-mcp --default-live-session
kwin-mcp-cli --default-live-session

利用可能なツール

セッション管理（3 ツール）

観察（3 ツール）

マウス入力（6 ツール）

キーボード入力（5 ツール）

タッチ入力（4 ツール）

クリップボード（2 ツール）

ウィンドウ管理（3 ツール）

UI のポーリング（1 ツール）

高度なツール（3 ツール）

フレームキャプチャ： 多くのアクションツールでは、任意の screenshot_after_ms パラメーター（例：[0, 50, 100, 200, 500]）を指定できます。アクションの完了後、指定した遅延時間（ミリ秒）でスクリーンショットをキャプチャします。追加の MCP ラウンドトリップなしで、ホバー効果、クリックアニメーション、メニューの遷移など、一時的な UI の状態を観察するのに便利です。フレームキャプチャでは、高速な KWin ScreenShot2 D-Bus インターフェースを使用します（1 フレームあたり約 30～70 ms）。

仕組み

Claude Code / AI Agent
  |
  |  MCP (stdio)
  v
kwin-mcp server  (30 tools)       kwin-mcp-cli (interactive REPL)
  |                                  |
  +--- both delegate to AutomationEngine (core.py) ---+
  |
  |-- session_start (virtual) ---> dbus-run-session
  |                                 |-- at-spi-bus-launcher
  |                                 +-- kwin_wayland --virtual
  |                                       +-- [your app]
  |
  |-- session_connect (live) ----> existing KWin (real desktop / container)
  |
  |-- screenshot ---------------> KWin ScreenShot2 D-Bus (spectacle fallback)
  |
  |-- accessibility_tree -------> AT-SPI2 (via PyGObject)
  |-- find_ui_elements ---------> AT-SPI2 (via PyGObject)
  |-- wait_for_element ----------> AT-SPI2 (polling)
  |
  |-- mouse_* ------------------> KWin EIS D-Bus --> libei
  |-- keyboard_* ---------------> KWin EIS D-Bus --> libei
  |-- touch_* ------------------> KWin EIS D-Bus --> libei
  |    +-- screenshot_after_ms -> KWin ScreenShot2 D-Bus (fast frame capture)
  |
  |-- keyboard_type_unicode ----> wtype / wl-copy + Ctrl+V
  |-- clipboard_* --------------> wl-copy / wl-paste (wl-clipboard)
  |
  |-- launch_app / list_windows / focus_window
  |                                |-- subprocess spawn
  |                                +-- AT-SPI2 (via PyGObject)
  |
  |-- dbus_call -----------------> dbus-send (generic D-Bus)
  |-- read_app_log --------------> log file read
  +-- wayland_info --------------> wayland-info

トリプル分離（＋オプションのホームディレクトリ分離）

kwin-mcp は、ホストのデスクトップから三層にわたって分離します。

1. D-Bus の分離 -- dbus-run-session により、プライベートなセッションバスが作成されます。分離されたセッションのサービス（KWin、AT-SPI2、ポータル）はホストから見えません。
2. ディスプレイの分離 -- kwin_wayland --virtual により、仮想フレームバッファーを備えた独自の Wayland コンポジターが作成されます。ホストのディスプレイにはウィンドウが表示されません。
3. 入力の分離 -- 入力イベントは KWin の EIS インターフェースを通じて、分離されたコンポジターにのみ送信されます。ホストのデスクトップは kwin-mcp から入力を受け取りません。
4. ホームディレクトリの分離（オプション） -- session_start で isolate_home=true を設定すると、分離された XDG ディレクトリ（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_CACHE_HOME、XDG_STATE_HOME）を含む一時的な HOME ディレクトリが作成されます。セッション内のアプリはホストユーザーの設定（例：~/.config/kdeglobals）を読み取ったり変更したりできないため、テストの再現性と安全性が向上します。Wayland ソケットが配置されているため、XDG_RUNTIME_DIR は意図的に分離されません。

入力の送信

マウス、キーボード、タッチのイベントは、KWin のプライベートな org.kde.KWin.EIS.RemoteDesktop D-Bus インターフェースを通じて送信されます。このインターフェースは libei のファイルディスクリプターを返すため、ユーザー認証ダイアログが表示される XDG RemoteDesktop ポータルを必要とせずに、低レベルの入力エミュレーションを行えます。この接続では、以下を使用します。

• 座標ベースの正確な操作のための絶対ポインター位置指定
• キーボード入力のための、完全な US QWERTY マッピングを備えた evdev キーコード
• リアルなドラッグ操作のためのスムーズなドラッグ補間（10 段階以上の中間ステップ）
• マルチタッチジェスチャー（タップ、スワイプ、ピンチ、複数指のスワイプ）のための EIS タッチエミュレーション

スクリーンショットの取得

screenshot ツールは KWin の org.kde.KWin.ScreenShot2 D-Bus インターフェースを通じてスクリーンショットを取得します（1 フレームあたり約 30～70 ミリ秒）。フォールバックとして spectacle CLI を使用します。screenshot_after_ms パラメーターを指定したアクションツールでも、高速な連続取得のために同じ D-Bus インターフェースを使用します。未加工の ARGB ピクセルデータはパイプから読み取られ、Pillow を使用して PNG に変換されます。

アクセシビリティツリー

分離されたセッション内の AT-SPI2 アクセシビリティバスは、PyGObject（gi.repository.Atspi）を介してクエリされます。これにより、役割（ボタン、テキストフィールド、メニュー項目など）、名前、状態（フォーカス中、有効、表示中など）、画面上の座標、利用可能なアクション（クリック、切り替えなど）を含む、すべての UI ウィジェットの構造化ツリーが提供されます。

システム要件

オプションの依存関係：

システム依存関係のインストール

sudo pacman -S kwin spectacle at-spi2-core python-gobject dbus-python-common

# Optional: for clipboard and Unicode input
sudo pacman -S wl-clipboard wtype wayland-utils

sudo dnf install kwin-wayland spectacle at-spi2-core python3-gobject dbus-python

# Optional: for clipboard and Unicode input
sudo dnf install wl-clipboard wtype wayland-utils

sudo zypper install kwin6 spectacle at-spi2-core python3-gobject python3-dbus-python

# Optional: for clipboard and Unicode input
sudo zypper install wl-clipboard wtype wayland-utils

sudo apt install kwin-wayland spectacle at-spi2-core python3-gi gir1.2-atspi-2.0 python3-dbus

# Optional: for clipboard and Unicode input
sudo apt install wl-clipboard wtype wayland-utils

Note：PyPI の kwin-mcp という名前は、上流プロジェクト（isac322/kwin-mcp、v0.7.0、MCP SDK 1.x）を参照しています。このリポジトリは積極的にメンテナンスされているフォーク（v0.9.0、MCP SDK 2.x）です。git またはソースのチェックアウトからインストールしてください。設定セクションにある uvx kwin-mcp の設定例は、PyPI パッケージを参照します。

uv を使用する（推奨）

uv tool install git+https://github.com/VibeProgramm/kwin-mcp

pip を使用する

pip install git+https://github.com/VibeProgramm/kwin-mcp

ソースからインストールする

git clone https://github.com/VibeProgramm/kwin-mcp.git
cd kwin-mcp
uv sync
uv run kwin-mcp

制限事項

• US QWERTY キーボードレイアウトのみ -- keyboard_type がサポートするのは US QWERTY のみです。ASCII 以外のテキスト（韓国語、CJK など）には、wtype または wl-clipboard のインストールが必要な keyboard_type_unicode を使用してください。
• KDE Plasma 6 以降が必要 -- 古い KDE バージョンや、その他の Wayland コンポジター（GNOME、Sway）はサポートされていません。
• AT-SPI2 の利用可否は異なります -- アプリケーションによっては、AT-SPI2 経由でウィジェットツリーを完全に公開しない場合があります。
• タッチ入力は EIS でエミュレートされます -- タッチイベントは実際のタッチスクリーンデバイスからではなく、KWin の EIS インターフェースを通じてエミュレートされます。ほとんどのアプリケーションはエミュレートされたタッチを正しく処理しますが、物理的なタッチとは異なる動作をする場合があります。
• クリップボードの使用にはオプトインが必要です -- wl-copy が隔離されたセッションでハングする可能性があるため、クリップボードツール（clipboard_get、clipboard_set）はデフォルトで無効になっています。session_start で enable_clipboard=true を設定して有効にし、wl-clipboard がインストールされていることを確認してください。
• QMenu（ネイティブのコンテキストメニュー）は AT-SPI2 に表示されない場合があります -- Qt の AT-SPI2 ブリッジは、Wayland 上のポップアップメニューのサポートが不完全です。コンテキストメニューが accessibility_tree や find_ui_elements に表示されない場合があります。回避策：screenshot を使用してメニュー項目の位置を視覚的に確認し、座標を指定してクリックしてください。
• 画面端のトリガーは EIS 入力では動作しません -- 自動非表示パネルや layer-shell のトリガーストリップは Wayland サーフェスの入力ルーティングに依存しており、EIS から注入されたポインターイベントに反応しない場合があります。回避策：代わりに KWin スクリプティングまたはキーボードショートカットで dbus_call を使用してください。
• AT-SPI2 の座標変換はベストエフォートです -- Wayland クライアントが報告するのはウィンドウ内の座標です（設計上、グローバルな画面上の位置は把握できません）。kwin-mcp は、各ウィンドウのコンポジター側のジオメトリ（KWin スクリプティングで取得し、キャプションで照合）を使用して、これらを実際の画面座標に変換します。ウィンドウを照合できない場合、座標はウィンドウ内の座標にフォールバックします。screenshot と照合して判別してください。

トラブルシューティングとデバッグ

詳細な libei/EIS 診断（KWIN_MCP_DEBUG_EI=1）

環境変数 KWIN_MCP_DEBUG_EI=1 を設定すると、EIS 入力注入経路（kwin-mcp から KWin への直接の libei 接続）の詳細な診断を有効にできます。

KWIN_MCP_DEBUG_EI=1 uv run kwin-mcp

有効にすると、kwin_mcp.input ロガーのレベルが DEBUG に引き上げられ、stderr ハンドラーが設定されます。また、EIS デバイスのライフサイクルイベント（ADDED / REMOVED / RESUMED / PAUSED / SEAT_REMOVED）、デバイスの停止、接続の再構築がログに記録されます。入力注入が何も起こさないまま失敗したり、不安定に動作したりする場合に使用してください。ログから、KWin が入力バーストの前後に EIS デバイスを一時停止または削除しているか、また kwin-mcp が接続を再構築できているかを確認できます。

KWIN_MCP_DEBUG_EI=1 uv run kwin-mcp 2>eis-debug.log

その他の症状

• session_start の出力に No input backend available と表示される — KWin が EIS RemoteDesktop インターフェースを公開していません。セッションはスクリーンショットと AT-SPI2 のみのセッション（入力注入なし）に切り替わります。KWin のバージョン（Plasma 6 が必要）と、切り替え理由が記載されたサーバーログを確認してください。
• 仮想セッションで keyboard_type_unicode が失敗する — kwin_wayland --virtual は wtype が必要とする virtual-keyboard プロトコルを公開しません。その環境ではクリップボードのフォールバック（wl-clipboard が必要）が主な経路です。

コントリビューション

コントリビューションを歓迎します！開発環境のセットアップ、コードスタイルのガイドライン、プルリクエストの手順については、CONTRIBUTING.md を参照してください。

git clone https://github.com/VibeProgramm/kwin-mcp.git
cd kwin-mcp
uv sync
uv run ruff check src/
uv run ruff format --check src/
uv run ty check src/

ライセンス

MIT