pyside6-mcp

Playwright-style MCP server for PySide6 apps — lets AI assistants see, control, and debug your Python desktop GUI without modifying your app's source code.

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

Features

• Screenshot any window or widget
• Inspect the full widget tree (class, name, geometry, text, state)
• Click, type, scroll, press keys — full interaction
• Find widgets by class, objectName, or text content
• Read Python logs captured from the app
• Run Python inside the app process for advanced inspection
• Launch and stop the app from the agent

Zero changes to your app's source code required.

Requirements

• Python 3.11+
• PySide6 6.6+
• uv (recommended)
• Windows (tested), Linux/macOS (should work)

Installation

The MCP server (stdio) and the in-app bridge are separate:

No changes to the target project. launch_app(cwd=…) injects only the bridge modules via an isolated PYTHONPATH — nothing is added to pyproject.toml, and the MCP server's dependencies (fastmcp, httpx, …) never enter the app environment.

Requires uv on PATH. MCP Registry name: io.github.com55/pyside6-mcp.

Unlike qt-mcp, you do not add this package to the target app or set a probe env var. launch_app injects the bridge.

Claude Code

Plugin (MCP + skill). install only searches marketplaces you have added — there is no github: install shorthand:

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

MCP server only:

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

Cursor

Install the Agent Plugin from this repository (or from the Cursor Marketplace once listed). Manual stdio config:

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

After saving, reload MCP servers in Cursor Settings → MCP. See examples/cursor-mcp-config.json.

Any stdio MCP client

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

Place it wherever that client expects MCP config (user-level or project-level). See examples/mcp-config.json.

VS Code / GitHub Copilot / other clients

Same stdio block as Any stdio MCP client.

Note: uvx downloads and runs the MCP server in an isolated env — PySide6 is not required there. PySide6 is only needed in the target app's venv (already a project dependency).

To run from a git checkout instead of PyPI: uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

Usage

From MCP (recommended — zero project setup)

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 is the project root (pyproject.toml). script is the entry .py relative to cwd.

launch_app returns {pid} (the Qt app process, not the uv wrapper). Other tools omit pid to target the last launched app; pass pid= when several are running. Do not pass port=.

Manual launch (when you start the app yourself)

Prefer launch_app above. Use

... View full README on GitHub