Submit
0xCarbon

qt-mcp

Community 0xCarbon
Updated

qt-mcp

qt-mcp

PyPIPythonCISecurityLicense

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

Tool Description
qt_snapshot Capture the full widget tree as a structured snapshot
qt_screenshot Take a screenshot of a widget or full window
qt_widget_details Get detailed properties of a specific widget
qt_click Click a widget (left/right/middle button, modifiers)
qt_type Type text into a widget
qt_key_press Send a key event (Return, Escape, Ctrl+S, etc.)
qt_set_property Set a Qt property on a widget
qt_invoke_slot Invoke a slot/method on a QObject
qt_list_windows List all top-level windows
qt_object_tree Get the full QObject parent-child tree
qt_scene_snapshot Get all items in a QGraphicsScene
qt_vtk_scene_info Get VTK scene state (camera, actors)
qt_vtk_screenshot Capture a VTK render window

Environment Variables

Variable Default Description
QT_MCP_PROBE unset Set to 1 to auto-activate the probe
QT_MCP_PORT 9142 Probe TCP listen port
QT_MCP_HOST localhost Probe TCP host (MCP server side)

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:

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.

MCP Server · Populars

MCP Server · New