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 these only when the app is already running, or you want to start it outside the MCP server.

Without editing app source — run the entry script through the bridge launcher (pulls pyside6-mcp into a temporary env; does not add it to the project):

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

Bridge listens on http://127.0.0.1:7890 by default. Override with PYSIDE6_MCP_PORT. Then from the agent call wait_until_ready() (and pass pid= only if you use several apps).

launch_app is different: it picks an ephemeral port and injects only the bridge modules via an isolated PYTHONPATH — you never set the port yourself.

Embed in the app (always-on; requires adding the package to that project):

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

From your AI assistant

Once the app is running with the bridge active, ask your assistant:

"Screenshot the app and click the Apply button" "Why is the checkbox disabled? Inspect its state." "Fill in the form and submit it" "Show me the last 20 log lines from the app"

Your assistant uses the launch_app, screenshot, get_widget_tree, find_widget, click, type_text, get_logs, and other tools automatically.

launch_app returns only when the UI is ready (a visible top-level window that has been quiet for at least 500 ms), not merely when the bridge HTTP server is up. Default timeout is 45 seconds.

Tools

Agent Skill

A companion skill ships at skills/pyside6-mcp/SKILL.md and is installed automatically with the plugin. It tells the agent when and how to use these tools — no need to explain the workflow every time.

Architecture

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>

Thread safety: all Qt operations are marshaled to the main thread via QApplication.postEvent with a custom event type — the same mechanism Qt uses internally for cross-thread signals.

Examples

• examples/test_app.py — minimal PySide6 app to verify the bridge
• examples/mcp-config.json — generic MCP config (Cursor, VS Code, Windsurf, …)
• examples/cursor-mcp-config.json — Cursor-specific template
• examples/claude-mcp-config.json — same format, kept for reference

License

MIT