PySide6 MCP — Claude Code MCP server: drive your GUI
Lets an AI assistant screenshot, inspect and click through a running PySide6 app. Your project's source stays untouched.
claude mcp add pyside6-mcp -- uvx pyside6-mcpWhat PySide6 MCP does
The flow is short: the assistant calls MCP tools, they hit a local HTTP bridge on an ephemeral port, and the bridge talks to the live app. launch_app(cwd=…) starts the program for you and returns once a visible top-level window has been quiet for a while. Bridge modules arrive through an isolated PYTHONPATH, so the server's own dependencies never land in the app environment.
The toolset covers screenshots, the full widget hierarchy, widget lookup by class, objectName or text, mouse clicks, keyboard input, named keys, app state and logs. get_widget_info dumps the properties of a single widget, and there is a way to run Python inside the app process when inspection alone is not enough.
You need Python 3.11+, PySide6 6.6+ and uv on PATH. Without uv nothing starts, since the server runs through uvx. Windows is the tested platform; Linux and macOS should follow. When you start the app yourself, the bridge listens on http://127.0.0.1:7890 and PYSIDE6_MCP_PORT changes that.
What it helps with
- capture a window or a single widget
- map the widget tree with classes and geometry
- locate an element by
objectNameor label text - fill a form and submit it with a click
- pull application logs into the chat
Example prompts for the agent
- Launch the app from
backend/gui.pyand screenshot the main window - Why is the checkbox disabled? Check its state with
get_widget_info
How to install PySide6 MCP
Platform CLI
claude mcp add pyside6-mcp -- uvx pyside6-mcpuvx runs the command named after the package; if the README names another one, use uvx --from pyside6-mcp <command>
Platform CLI
codex mcp add pyside6-mcp -- uvx pyside6-mcpuvx runs the command named after the package; if the README names another one, use uvx --from pyside6-mcp <command>
Config file
{
"mcpServers": {
"pyside6-mcp": {
"command": "uvx",
"args": [
"pyside6-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from pyside6-mcp <command>
Config file
{
"servers": {
"pyside6-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"pyside6-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from pyside6-mcp <command>
Platform CLI
gemini mcp add pyside6-mcp uvx pyside6-mcpuvx runs the command named after the package; if the README names another one, use uvx --from pyside6-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about PySide6 MCP
How do I install PySide6 MCP in Claude Code?
Run claude mcp add pyside6-mcp -- uvx pyside6-mcp. That registers the stdio server in your user-level config.
What does PySide6 MCP do?
It gives the assistant eyes and hands inside a PySide6 app: screenshots, widget tree, clicks, typing, log reading. No edits to your project's code.
Do I have to add the package to my project?
No. launch_app injects the bridge modules through a separate PYTHONPATH, and pyproject.toml stays as it was. Adding the package is only for an always-on bridge via install_bridge().
