使用说明
qt mcp
MCP（模型上下文协议）服务器，用于检查、调试和与Qt/PySide6桌面应用程序交互，如Playwright MCP，但用于桌面Qt应用程序。
概述
qt-mcp为AI编码代理提供了运行PySide6应用程序的完全可见性：
- 小部件树快照 --整个UI的结构化可访问性视图
- 财产清查 --读取任何小部件上的所有Qt属性
- 交互 --单击按钮、键入文本、按键
- 截图 --将任何小部件或整个窗口捕获为PNG
- Q图形现场检查 --列举并检查现场项目
- VTK/PyVista支持 --检查3D场景并捕获渲染
建筑
┌─────────────────────────────────────────────┐
│ Target PySide6 Application │
│ ┌───────────────────────────────────────┐ │
│ │ qt-mcp Probe (in-process) │ │
│ │ • QObject tree traversal │ │
│ │ • Property read/write │ │
│ │ • Widget.grab() screenshots │ │
│ │ • Event injection (click/type) │ │
│ │ Listens on: localhost:9142 │ │
│ └───────────────────────────────────────┘ │
└──────────────────┬──────────────────────────┘
│ JSON-RPC over TCP
┌──────────────────┴──────────────────────────┐
│ qt-mcp MCP Server (separate process) │
│ • Speaks MCP protocol (stdio) to Claude │
│ • Translates tool calls → probe RPCs │
└─────────────────────────────────────────────┘
安装
# Install with uv
uv add qt-mcp
# Or install from source
git clone https://github.com/0xCarbon/qt-mcp.git
cd qt-mcp
uv sync --extra dev
快速开始
1.检测你的应用程序
将探测器添加到PySide6应用程序中：
# Option A: Environment variable (preferred)
# QT_MCP_PROBE=1 python -m your_app
# Option B: Explicit init
from qt_mcp.probe import install
install() # call after QApplication is created
2.配置克劳德代码
添加到MCP设置中：
{
"mcpServers": {
"qt-mcp": {
"command": "uvx",
"args": ["qt-mcp"]
}
}
}
3.使用Claude
Claude现在可以查看您的Qt应用程序并与之交互：
“拍摄正在运行的应用程序的快照” “单击“应用”按钮” “在搜索字段中键入'hello'” “显示3D视图的屏幕截图”
MCP工具
| 工具 | 说明 |
|---|---|
qt_snapshot |
将整个小部件树捕获为结构化快照 |
qt_screenshot |
截取小部件或整个窗口的屏幕截图 |
qt_widget_details |
获取特定小部件的详细属性 |
qt_click |
单击小部件（左/右/中按钮、修饰符） |
qt_type |
在小部件中键入文本 |
qt_key_press |
发送关键事件（返回、转义、Ctrl+S等） |
qt_set_property |
在小部件上设置Qt属性 |
qt_invoke_slot |
在QObject上调用插槽/方法 |
qt_list_windows |
列出所有顶级窗口 |
qt_object_tree |
获取完整的QObject父子树 |
qt_scene_snapshot |
获取QGraphicsScene中的所有项目 |
qt_vtk_scene_info |
获取VTK场景状态（摄像机、演员） |
qt_vtk_screenshot |
捕获VTK渲染窗口 |
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
QT_MCP_PROBE |
unset | 设置为 1 自动激活探头 |
QT_MCP_PORT |
9142 |
探测TCP侦听端口 |
QT_MCP_HOST |
localhost |
探测TCP主机（MCP服务器端） |
发展
# Install dev dependencies
uv sync --extra dev
# Run tests
uv run pytest -v
# Format
uv run ruff format src/ tests/
# Lint
uv run ruff check src/ tests/
# Security audit
uv run pip-audit --progress-spinner off
gitleaks detect --source . --config .gitleaks.toml
故障排除
探头未连接
- 确保探头安装在目标应用程序中（检查
qt_mcp_probe在QApplication.children()) - 验证探测器和MCP服务器之间的端口匹配(
QT_MCP_PORT) - 检查端口9142是否有其他东西在使用
Wayland问题
QWidget.grab()在X11和Wayland上从流程内部工作- 外部截图工具可能需要Wayland上的门户授权
OpenGL小部件
QOpenGLWidget.grab()需要一个真正的显示服务器（X11/Wayland）- 在屏幕外平台上，grab（）返回一个有效的像素图，但没有GL内容
- 标准小部件和QGraphicsView在屏幕外工作良好
许可证
根据以下任一方式获得许可：
- Apache许可证，版本2.0(特许通行证 或 https://www.apache.org/licenses/LICENSE-2.0)
- MIT许可证(许可证-麻省理工学院 或 https://opensource.org/licenses/MIT)
由您选择。
贡献
看 贡献.md 用于开发工作流程和贡献要求。
行为准则
安全
看 安全.md 报告漏洞。
