PySide6 MCP

pyside6-mcp

适用于 PySide6 应用的 Playwright 风格 MCP 服务 — 让 AI 助手无需修改应用源代码，即可查看、控制和调试你的 Python 桌面 GUI。

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

功能

• 截取任意窗口或控件的屏幕截图
• 检查完整的控件树（类、名称、几何信息、文本、状态）
• 点击、输入、滚动、按键 — 完整交互
• 按类、objectName 或文本内容查找控件
• 读取从应用捕获的 Python 日志
• 在应用进程内运行 Python，以进行高级检查
• 通过 Agent 启动和停止应用

无需对应用源代码做任何更改。

要求

• Python 3.11+
• PySide6 6.6+
• uv（推荐）
• Windows（已测试）、Linux/macOS（应该可用）

安装

MCP 服务（stdio）和应用内桥接模块是分开的：

组件	运行位置	需要 PySide6？
MCP 服务（pyside6-mcp）	MCP 客户端进程	否
桥接模块（python -m pyside6_mcp …）	PySide6 应用内部	是

无需修改目标项目。 launch_app(cwd=…) 仅通过隔离的 PYTHONPATH 注入桥接模块 — 不会向 pyproject.toml 添加任何内容，MCP 服务的依赖项（fastmcp、httpx、…）也不会进入应用环境。

要求 PATH 中有 uv。MCP Registry 名称： io.github.com55/pyside6-mcp。

与 qt-mcp 不同，你无需将此 软件包添加到目标应用，也无需设置探针环境变量。launch_app 会注入桥接模块。

Claude Code

插件（MCP + 技能）。install 只会搜索你已添加的 marketplace — 没有 github: 安装简写：

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

仅 MCP 服务：

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

Cursor

从此仓库安装 Agent Plugin（或待其上架后从 Cursor Marketplace 安装）。手动配置 stdio：

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

保存后，在 Cursor Settings → MCP 中重新加载 MCP 服务。 参见 examples/cursor-mcp-config.json。

任意 stdio MCP 客户端

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

将其放在该客户端存放 MCP 配置的位置（用户级或项目级）。 参见 examples/mcp-config.json。

VS Code / GitHub Copilot / 其他客户端

与 任意 stdio MCP 客户端使用相同的 stdio 配置块。

注意： uvx 会在隔离环境中下载并运行 MCP 服务 — 此处不需要 PySide6。只有目标应用的 venv 中需要 PySide6（它已经是项目依赖项）。

若要从 git checkout 而非 PyPI 运行：uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

用法

通过 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 launched

cwd 是项目根目录（pyproject.toml）。script 是相对于 cwd 的入口 .py 文件。

launch_app 返回 {pid}（Qt 应用进程，而非 uv 包装进程）。其他工具省略 pid 时会以最后启动的应用为目标；有多个应用在运行时，传入 pid=。不要传入 port=。

手动启动（当你自行启动应用时）

优先使用上面的 launch_app。仅当应用已在运行，或你想在 MCP 服务之外启动应用时，才使用以下方法。

无需编辑应用源代码 — 通过桥接启动器运行入口脚本 （将 pyside6-mcp 拉取到临时环境；不会将其添加到项目中）：

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

桥接模块默认监听 http://127.0.0.1:7890。使用 PYSIDE6_MCP_PORT 覆盖。然后从 Agent 调用 wait_until_ready()（只有在使用多个应用时才传入 pid=）。

launch_app 的方式不同：它会选择一个临时端口，并通过隔离的 PYTHONPATH 仅注入桥接模块 — 你无需自行设置端口。

嵌入应用（始终运行；需要将软件包添加到该项目中）：

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

来自你的 AI 助手

应用运行且桥接已激活后，向你的助手提出以下请求：

“截取应用的屏幕截图并点击 Apply 按钮” “为什么复选框处于禁用状态？检查它的状态。” “填写表单并提交” “显示应用最近 20 行日志”

你的助手会自动使用 launch_app、screenshot、get_widget_tree、find_widget、click、type_text、get_logs 等工具。

launch_app 只有在 UI 就绪时才会返回（存在可见的顶层窗口，且至少 500 ms 内没有变化），而不只是桥接 HTTP 服务器已启动时。默认 timeout 为 45 秒。

工具

工具	描述
launch_app(cwd, script?, app_args?, timeout)	启动应用（不安装目标项目）并等待 UI 就绪。返回 {pid}
list_apps()	列出此服务启动的应用 PID
get_launch_help()	查看如何在启动前设置 cwd、script、app_args
wait_until_ready(timeout, quiet_ms, pid?)	等待正在运行的应用 UI 就绪
wait_for_idle(timeout, quiet_ms, pid?)	等待操作完成后 UI 保持静止
get_app_status(pid?)	检查进程和桥接健康状况；检测可能的模态阻塞
stop_app(pid?)	停止已启动的应用
screenshot(widget_id?, pid?)	截取窗口或特定组件的屏幕截图（识别模态窗口／活动窗口）
get_widget_tree(pid?)	获取包含 ID 的完整组件层级
get_widget_info(widget_id, pid?)	获取单个组件的详细属性
get_app_state(pid?)	获取活动窗口、焦点和屏幕信息
find_widget(class_name?, object_name?, text?, visible?, pid?)	搜索组件
click(widget_id?, x?, y?, button?, pid?)	鼠标点击
double_click(widget_id, x?, y?, pid?)	双击
type_text(text, widget_id?, pid?)	键盘输入
press_key(key, pid?)	指定按键：enter、escape、tab、up/down、f5、…
scroll(dy, widget_id?, dx?, pid?)	滚动滚轮
list_actions(pid?)	列出 QAction 菜单／工具栏项目
trigger_action(name?, text?, pid?)	无需点击菜单即可触发 QAction
get_logs(n?, pid?)	获取最近的 Python 日志记录
get_app_output(n?, pid?)	获取已启动应用的原始 stdout/stderr
eval_python(code, pid?)	在应用进程内执行 Python

Agent 技能

随附技能位于 skills/pyside6-mcp/SKILL.md， 并会随插件自动安装。它会告诉 Agent 何时以及如何使用这些工具——无需每次 都解释工作流。

架构

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>

线程安全：所有 Qt 操作都会通过 QApplication.postEvent 和自定义事件类型调度到主线程——这与 Qt 内部用于跨线程信号的机制相同。

示例

• examples/test_app.py — 用于验证桥接的最简 PySide6 应用
• examples/mcp-config.json — 通用 MCP 配置（Cursor、VS Code、Windsurf、…）
• examples/cursor-mcp-config.json — Cursor 专用模板
• examples/claude-mcp-config.json — 相同格式，仅供参考

许可证

MIT