qt-mcp

MCP (Model Context Protocol) server for inspecting, debugging, and interacting with Qt/PySide6 desktop applications — like Playwright MCP, but for desktop Qt apps.

Overview

qt-mcp gives AI coding agents full visibility into running PySide6 applications:

• Widget tree snapshots — structured accessibility-like view of the entire UI
• Property inspection — read all Qt properties on any widget
• Interaction — click buttons, type text, press keys
• Screenshots — capture any widget or full window as PNG
• QGraphicsScene inspection — enumerate and inspect scene items
• VTK/PyVista support — inspect 3D scenes and capture renders

Architecture

┌─────────────────────────────────────────────┐
│  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       │
└─────────────────────────────────────────────┘

Installation

# 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

Quick Start

1. Instrument your app

Add the probe to your PySide6 application:

# 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. Configure Claude Code

Add to your MCP settings:

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

3. Use from Claude

Claude can now see and interact with your Qt app:

"Take a snapshot of the running application" "Click the 'Apply' button" "Type 'hello' into the search field" "Show me a screenshot of the 3D view"

MCP Tools

Environment Variables

Development

# 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

Troubleshooting

Probe not connecting

• Ensure the probe is installed in the target app (check for qt_mcp_probe in QApplication.children())
• Verify the port matches between probe and MCP server (QT_MCP_PORT)
• Check that nothing else is using port 9142

Wayland issues

• QWidget.grab() works from inside the process on both X11 and Wayland
• External screenshot tools may require portal authorization on Wayland

OpenGL widgets

• QOpenGLWidget.grab() requires a real display server (X11/Wayland)
• With offscreen platform, grab() returns a valid pixmap but without GL content
• Standard widgets and QGraphicsView work fine offscreen

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contributing

See CONTRIBUTING.md for development workflow and contribution requirements.

Code of Conduct

See CODE_OF_CONDUCT.md.

Security

See SECURITY.md to report vulnerabilities.