qt MCP

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工具

环境变量

发展

# 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(特许通行证 或 )
• MIT许可证(许可证-麻省理工学院 或 )

由您选择。

贡献

看 贡献.md 用于开发工作流程和贡献要求。

行为准则

看 代码_OF_CONDUCT.md.

安全

看 安全.md 报告漏洞。