PySide6 MCP

pyside6-mcp

PySide6 アプリ向けの Playwright スタイルの MCP サーバーです。アプリのソースコードを変更せずに、AI アシスタントが Python デスクトップ GUI の表示、操作、デバッグを行えます。

AI assistant → MCP tools → pyside6-mcp server → HTTP bridge (ephemeral localhost port) → PySide6 app

機能

• 任意のウィンドウやウィジェットのスクリーンショットを撮影
• ウィジェットツリー全体を検査（クラス、名前、ジオメトリ、テキスト、状態）
• クリック、入力、スクロール、キーの押下など、すべての操作に対応
• クラス、objectName、テキストの内容でウィジェットを検索
• アプリから取得したPython ログを読み取り
• 高度な検査のために、アプリのプロセス内でPython を実行
• エージェントからアプリを起動および停止

アプリのソースコードを変更する必要はありません。

要件

• Python 3.11+
• PySide6 6.6+
• uv（推奨）
• Windows（テスト済み）、Linux/macOS（動作するはずです）

インストール

MCP サーバー（stdio）とアプリ内ブリッジは別々です。

コンポーネント	実行場所	PySide6 が必要ですか？
MCP サーバー（pyside6-mcp）	MCP クライアントのプロセス	いいえ
ブリッジ（python -m pyside6_mcp …）	PySide6 アプリ内	はい

対象プロジェクトを変更する必要はありません。 launch_app(cwd=…) は、分離された PYTHONPATH を通じてブリッジモジュールのみを注入します。pyproject.toml に追加されるものはなく、 MCP サーバーの依存関係（fastmcp、httpx、…）がアプリの環境に入ることもありません。

PATH 上に uv が必要です。MCP Registry 名： io.github.com55/pyside6-mcp。

qt-mcp とは異なり、このパッケージを対象アプリに追加したり、 プローブ用の環境変数を設定したりする必要はありません。launch_app がブリッジを注入します。

Claude Code

プラグイン（MCP + スキル）。install が検索するのは、追加済みのマーケットプレイスのみです。 github: によるインストールの省略形はありません。

claude plugin marketplace add com55/pyside6-mcp
claude plugin install pyside6-mcp@pyside6-mcp

MCP サーバーのみ：

claude mcp add -s user pyside6 -- uvx pyside6-mcp

Cursor

このリポジトリ（または掲載後は Cursor Marketplace）から Agent Plugin をインストールします。stdio の手動設定：

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

保存後、Cursor Settings → MCP で MCP サーバーを再読み込みしてください。 examples/cursor-mcp-config.json を参照してください。

任意の stdio MCP クライアント

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

そのクライアントが MCP 設定を読み込む場所（ユーザーレベルまたはプロジェクトレベル）に配置します。 examples/mcp-config.json を参照してください。

VS Code / GitHub Copilot / その他のクライアント

任意の stdio MCP クライアントと同じ stdio ブロックを使用します。

注： uvx は MCP サーバーを分離された環境にダウンロードして実行するため、そこで PySide6 は不要です。 PySide6 が必要なのは対象アプリの venv 内だけです（すでにプロジェクトの依存関係に含まれています）。

PyPI ではなく git checkout から実行するには、次を使用します：uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

使用方法

MCP から使用（推奨 — プロジェクトのセットアップは不要）

launch_app(cwd="/path/to/project")                              # main.py at root
launch_app(cwd="/path/to/project", script="app.py")             # other name at root
launch_app(cwd="/path/to/project", script="backend/gui.py")   # entry in subfolder
get_launch_help()                                               # full script decision guide
list_apps()                                                     # pids of apps this server launched

cwd はプロジェクトルート（pyproject.toml）です。script は cwd からの相対パスで指定するエントリー .py ファイルです。

launch_app は {pid}（Qt アプリのプロセス。uv ラッパーではありません）を返します。他のツールでは pid を省略すると、最後に起動したアプリが対象になります。複数のアプリが実行中の場合は pid= を渡してください。port= は渡さないでください。

手動で起動（自分でアプリを起動する場合）

上記の launch_app を推奨します。以下の方法は、アプリがすでに実行中の場合、または MCP サーバーの外部でアプリを起動する場合にのみ使用してください。

アプリのソースを編集せずに実行 — エントリースクリプトをブリッジランチャー経由で実行します （pyside6-mcp を一時環境に取得します。プロジェクトには追加されません）。

cd your-pyside6-project
uv run --with pyside6-mcp python -m pyside6_mcp main.py
# other entry: … python -m pyside6_mcp app.py
# in a subfolder: … python -m pyside6_mcp backend/gui.py

ブリッジはデフォルトで http://127.0.0.1:7890 をリッスンします。PYSIDE6_MCP_PORT で変更できます。 その後、エージェントから wait_until_ready() を呼び出します（複数のアプリを使用する場合にのみ pid= を渡してください）。

launch_app は動作が異なります。一時ポートを選び、分離された PYTHONPATH を通じて ブリッジモジュールのみを注入するため、ポートを自分で設定する必要はありません。

アプリに組み込む（常時有効。プロジェクトへのパッケージ追加が必要です）：

uv add pyside6-mcp

# In your app's main(), after QApplication is created and before app.exec()
from pyside6_mcp import install_bridge
install_bridge()  # same default port 7890 / PYSIDE6_MCP_PORT

AI アシスタントから

ブリッジを有効にしてアプリを実行したら、アシスタントに次のように依頼します。

「アプリのスクリーンショットを撮って、Apply ボタンをクリックしてください」 「チェックボックスが無効なのはなぜですか？ 状態を調べてください」 「フォームに入力して送信してください」 「アプリの直近のログを20行表示してください」

アシスタントは、launch_app、screenshot、get_widget_tree、find_widget、click、type_text、get_logsなどのツールを自動的に使用します。

launch_appは、ブリッジのHTTPサーバーが起動しただけではなく、UIの準備ができたとき（トップレベルのウィンドウが表示され、少なくとも500 ms間静止した状態）にのみ戻ります。デフォルトのtimeoutは45秒です。

ツール

ツール	説明
launch_app(cwd, script?, app_args?, timeout)	アプリを起動し（対象プロジェクトへのインストールは不要）、UIの準備ができるまで待機します。{pid}を返します
list_apps()	このサーバーが起動したアプリのPID
get_launch_help()	起動前にcwd、script、app_argsを設定する方法
wait_until_ready(timeout, quiet_ms, pid?)	実行中のアプリのUIの準備ができるまで待機します
wait_for_idle(timeout, quiet_ms, pid?)	操作後、UIが静止するまで待機します
get_app_status(pid?)	プロセスとブリッジの状態を確認し、モーダルによるブロックの可能性を検出します
stop_app(pid?)	起動したアプリを停止します
screenshot(widget_id?, pid?)	ウィンドウまたは特定のウィジェットをキャプチャします（モーダル／アクティブウィンドウを認識します）
get_widget_tree(pid?)	IDを含むウィジェット階層全体
get_widget_info(widget_id, pid?)	1つのウィジェットの詳細なプロパティ
get_app_state(pid?)	アクティブウィンドウ、フォーカス、画面情報
find_widget(class_name?, object_name?, text?, visible?, pid?)	ウィジェットを検索します
click(widget_id?, x?, y?, button?, pid?)	マウスクリック
double_click(widget_id, x?, y?, pid?)	ダブルクリック
type_text(text, widget_id?, pid?)	キーボード入力
press_key(key, pid?)	名前付きキー：enter、escape、tab、up/down、f5、…
scroll(dy, widget_id?, dx?, pid?)	マウスホイールでスクロールします
list_actions(pid?)	QActionのメニュー／ツールバー項目を一覧表示します
trigger_action(name?, text?, pid?)	メニューをクリックせずにQActionを実行します
get_logs(n?, pid?)	最近のPythonログレコード
get_app_output(n?, pid?)	起動したアプリの標準出力／標準エラーを生のまま取得します
eval_python(code, pid?)	アプリのプロセス内でPythonを実行します

エージェントスキル

付属のスキルはskills/pyside6-mcp/SKILL.mdにあり、 プラグインとともに自動的にインストールされます。このスキルでは、これらのツールを いつ、どのように使用するかをエージェントに指示するため、毎回ワークフローを説明する必要はありません。

アーキテクチャ

pyside6_mcp/
├── bridge.py      # In-process HTTP server (runs inside the target app)
├── launch.py      # Isolated PYTHONPATH inject + launch_app argv/validation
├── session.py     # Handshake + in-memory pid → port sessions
├── server.py      # FastMCP stdio server (the MCP client talks to this)
├── __init__.py    # Exports install_bridge()
└── __main__.py    # Launcher: python -m pyside6_mcp <script>

スレッドセーフティ：すべてのQt操作は、カスタムイベントタイプを指定したQApplication.postEventを使ってメインスレッドにマーシャリングされます。これは、Qtがスレッド間シグナルに内部で使用するものと同じ仕組みです。

使用例

• examples/test_app.py — ブリッジの動作確認用の最小限のPySide6アプリ
• examples/mcp-config.json — 汎用MCP設定（Cursor、VS Code、Windsurf、…）
• examples/cursor-mcp-config.json — Cursor固有のテンプレート
• examples/claude-mcp-config.json — 同じ形式の設定ファイル。参考用に保持しています

ライセンス

MIT