This server is an MCP bridge for AI assistants to launch, inspect, interact with, and debug PySide6 desktop apps (no source modifications).
Launch & manage apps – launch_app launches a project with the bridge injected and waits for UI readiness; list_apps/stop_app manage launched app processes.
See the UI – screenshot captures a window or widget; get_widget_tree/get_widget_info/get_app_state expose the widget hierarchy, properties, active window, and focus.
Find widgets – search by class, object name, text, or visibility.
Interact – click, double-click, type text, press named/single keys, and scroll within a widget or the main window.
Trigger actions – list and invoke QAction menu/toolbar items without opening menus.
Debug – read captured Python logs and raw stdout/stderr, and eval_python runs arbitrary code inside the app process.
Synchronize – wait_until_ready/wait_for_idle/get_app_status check UI readiness and health (including modal blocks).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pyside6-mcp Screenshot the app and click the Login button"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 appScreenshot 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.
Related MCP server: uiautomation-mcp
Python 3.11+
PySide6 6.6+
uv (recommended)
Windows (tested), Linux/macOS (should work)
The MCP server (stdio) and the in-app bridge are separate:
Component | Where it runs | Needs PySide6? |
MCP server ( | MCP client's process | No |
Bridge ( | Inside your PySide6 app | Yes |
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.
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-mcpMCP server only:
claude mcp add -s user pyside6 -- uvx pyside6-mcpInstall 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.
{
"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.
Same stdio block as Any stdio MCP client.
Note:
uvxdownloads 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
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 launchedcwd 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=.
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.pyBridge 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_PORTOnce 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.
Tool | Description |
| Launch app (no target-project install) and wait for UI readiness. Returns |
| Pids of apps launched by this server |
| How to set cwd, script, app_args before launch |
| Wait for UI readiness on an already-running app |
| Wait until UI has been quiet after an action |
| Process + bridge health; detects likely modal blocks |
| Stop a launched app |
| Capture window or specific widget (modal/active-window aware) |
| Full widget hierarchy with IDs |
| Detailed properties of one widget |
| Active window, focus, screen info |
| Search widgets |
| Mouse click |
| Double click |
| Keyboard input |
| Named key: enter, escape, tab, up/down, f5, … |
| Scroll wheel |
| List QAction menu/toolbar items |
| Trigger a QAction without clicking menus |
| Recent Python log records |
| Raw stdout/stderr from launched app |
| Execute Python inside the app process |
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.
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/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
MIT
Click a widget or screen coordinate.
widget_id only: clicks the center of that widget
widget_id + x/y: clicks at (x, y) relative to the widget's top-left
x/y only: clicks at (x, y) relative to the main window button: 'left' (default), 'right', or 'middle'
Inputs: x, y, pid, button, +1 more. Returns: result
Double-click a widget. Sends two rapid left-clicks.
Inputs: widget_id (required), x, y, pid. Returns: result
Evaluate a Python expression or execute a statement inside the app process. Context provides:
app: QApplication instance
widgets: dict mapping widget_id → QWidget Examples: eval_python("app.activeWindow().windowTitle()") eval_python("widgets['3'].isEnabled()") eval_python("list(app.allWidgets())") WARNING: runs arbitrary code in the app — use only for debugging.
Inputs: code (required), pid. Returns: result
Search for widgets by class, objectName, text content, or visibility. Returns a list of matching widgets with their IDs. Examples: find_widget(class_name="QPushButton") find_widget(text="Apply Mods") find_widget(object_name="enabledCheckBox")
Inputs: pid, text, visible, class_name, +1 more. Returns: result
Get the last n lines of the launched app's real stdout/stderr: print() output, uncaught tracebacks, and Qt/console warnings.
This is the app's actual console output, captured because launch_app redirects it to a log file. Use this to debug crashes or startup failures. For structured Python logging records use get_logs() instead.
Only works for apps started via launch_app on this server.
Inputs: n, pid. Returns: result
Get app-level state: active window, focused widget, screen info. Useful to understand focus before sending keyboard events.
Inputs: pid. Returns: result
Report combined health of a launched app: whether the process is alive, its exit code, whether the bridge responds, and whether the main thread is likely blocked by a modal dialog (process alive but bridge unresponsive).
Inputs: pid. Returns: result
Return how to call launch_app — especially the script parameter.
Call this before launch_app when you are unsure which entry .py to use or whether script should include a subfolder path.
Inputs: no named parameters. Returns: result
Get the last n log messages captured from the app's Python logging system. Includes timestamp, level, logger name, and message.
Inputs: n, pid. Returns: result
Get detailed properties and state of a specific widget. Includes geometry, text, enabled/visible state, and dynamic Qt properties.
Inputs: widget_id (required), pid. Returns: result
Get the full widget hierarchy of all visible windows as JSON. Each widget has: id, class, object_name, visible, enabled, geometry, text, children. Use widget IDs from this tree in other tools.
Inputs: pid. Returns: result
Launch a PySide6 app with the MCP bridge injected, then wait until the UI is ready.
Inputs: cwd (required), script, command, timeout, +1 more. Returns: result
List all QActions (menu items, toolbar actions) in visible windows with their name, text, shortcut, and enabled/checked state.
Inputs: pid. Returns: result
List apps launched by this MCP server. Each entry is {pid}. Pass pid= to other tools when more than one app is running.
Inputs: no named parameters. Returns: result
Press a key on the currently focused widget. Named keys: enter, return, escape, tab, backtab, backspace, delete, up, down, left, right, space, home, end, pageup, pagedown, f1–f6 Single characters: pass the character directly, e.g. 'a', 'A', '1'
Inputs: key (required), pid. Returns: result
Capture a screenshot of the app window (or a specific widget by ID). Returns the image so you can see the current UI state. Call this first to orient yourself.
Inputs: pid, widget_id.
Scroll a widget. dy > 0 scrolls down, dy < 0 scrolls up. dx: horizontal scroll (positive = right). widget_id: target widget; omit to scroll the main window.
Inputs: dy (required), dx, pid, widget_id. Returns: result
Stop a previously launched app (started via launch_app). Omit pid to stop the last launched app.
Inputs: pid. Returns: result
Trigger a QAction directly by objectName (name) or visible label (text),
without clicking through menus. Useful to avoid opening modal menus and to
reach toolbar/menu actions reliably. Provide at least one of name/text.
Inputs: pid, name, text. Returns: result
Type text into a widget (focuses it first) or the currently focused widget. For special characters use press_key instead.
Inputs: text (required), pid, widget_id. Returns: result
Wait until the app's UI has been quiet (no layout/paint activity) for
quiet_ms ms, or until timeout seconds elapse. Call after a click or
action that triggers async work, before taking a screenshot.
Inputs: pid, timeout, quiet_ms. Returns: result
Wait until the app UI is ready: a visible top-level window that has been
quiet (no layout/paint activity) for quiet_ms milliseconds.
Use after an action that reloads or rebuilds the UI. Returns the readiness snapshot. Does not launch anything — the app must already be running.
Inputs: pid, timeout, quiet_ms. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 22 tools
Most tools target distinct resources/actions: screenshot/tree/info/find for inspection, click/type/press/scroll for input, launch/stop/status for lifecycle. A couple of pairs could be confused: wait_until_ready vs wait_for_idle and get_app_state vs get_app_status, though their descriptions separate them.
The set predominantly uses snake_case verb phrases such as get_widget_tree, list_actions, launch_app, and trigger_action. Minor deviations like the noun command 'screenshot' and a few bare verbs (click, scroll) keep it from being perfectly uniform, but the overall pattern is predictable.
22 tools is on the heavy side for an MCP surface, and some functionality (wait_until_ready/wait_for_idle, get_app_state/get_app_status, get_logs/get_app_output) could potentially be consolidated. Still, the count is defensible given the breadth of UI automation and debugging features.
The set covers the full lifecycle of launching, inspecting, interacting with, waiting on, and stopping a PySide6 app, plus logs and QAction access. There are minor gaps such as no direct property-mutation or drag/drop tool, but eval_python and existing input tools provide workarounds.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Live browser debugging for AI assistants — DOM, console, network via MCP.
