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):

claude plugin install github:com55/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 equivalent (same isolated PYTHONPATH that launch_app builds)

cd your-pyside6-project
# PYTHONPATH must point at a directory that contains *only* pyside6_mcp
# (bridge modules). Do not point it at the MCP server's site-packages.
uv run python -m pyside6_mcp main.py

The bridge starts automatically. Manual runs default to http://127.0.0.1:7890 (override with PYSIDE6_MCP_PORT). launch_app always uses an ephemeral port.

Or: embed the bridge (optional, for always-on)

# In your app's main(), before app.exec()
from pyside6_mcp import install_bridge
install_bridge()

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