1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qt-mcp Take a snapshot of the UI and click the 'Submit' button" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

qt-mcp

PyPI Python Security License

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:

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.

qt-mcp

qt-mcp

Overview

Architecture

Installation

Quick Start

1. Instrument your app

2. Configure Claude Code

3. Use from Claude

MCP Tools

Environment Variables

Development

Troubleshooting

Probe not connecting

Wayland issues

OpenGL widgets

License

Contributing

Code of Conduct

Security

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API