home / mcp / qt mcp server

Qt MCP Server

Provides an MCP server to inspect, control, and interact with PySide6 Qt desktop applications from an AI client.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "0xcarbon-qt-mcp": {
      "command": "uvx",
      "args": [
        "qt-mcp"
      ],
      "env": {
        "QT_MCP_HOST": "localhost",
        "QT_MCP_PORT": "9142",
        "QT_MCP_PROBE": "1"
      }
    }
  }
}

qt-mcp is a dedicated MCP server that lets you inspect, debug, and interact with PySide6 Qt desktop applications. By instrumenting your app with the probe, you gain full visibility into the widget tree, properties, and events, plus the ability to capture screenshots, inspect 3D scenes, and drive interactions from an external client. This makes AI coding agents more capable when working with desktop Qt apps.

How to use

You run the MCP server separately and connect to it from your MCP client (for example, Claude). First, ensure your target Qt application is instrumented with the probe, then configure your client to talk to the MCP server. Once connected, you can take snapshots of the widget tree, read and set Qt properties, click widgets, type text, press keys, and request screenshots or scene information. All actions are performed through the MCP interface and translated into probe operations inside your Qt process.

Typical usage flow: - Instrument your app to enable the probe - Start the MCP server and confirm it is listening on the configured host/port - In your MCP client, select the qt-mcp server and issue commands such as taking a widget tree snapshot, clicking a button, or capturing a screenshot - Review responses and iterate your automation or debugging tasks accordingly.

How to install

Prerequisites: Python environment with the ability to install the qt-mcp package and a toolchain to run the MCP server adapter.

Step 1 — Install with uv

uv add qt-mcp

Step 2 — Or install from source

git clone https://github.com/0xCarbon/qt-mcp.git
cd qt-mcp
uv sync --extra dev

Additional sections

Configuration notes, security considerations, and troubleshooting are provided below to help you run the MCP server smoothly and safely.

Instrumenting your application enables the probe to be discovered by the MCP server over the local loopback interface. The probe listens for connections from the MCP server, and the server translates client commands into probe RPCs inside the Qt process.

Troubleshooting quick tips: - If the probe is not connecting, verify that the probe is installed in your target app and that the port matches between the probe and the MCP server - Check for port conflicts on the configured host/port - Ensure the target Qt session is running and accessible by the MCP server - On Wayland or OpenGL contexts, capture behavior may vary; ensure a real display is available for certain screenshots.

Notes on usage with Claude and MCP tools

Configure Claude to use the qt-mcp server by adding an MCP server entry that points to the local proxy. The example below shows how to run the MCP server as a local process using uvx and connect to it from your client.

Available tools

qt_snapshot

Capture the full widget tree as a structured snapshot for analysis by the MCP client.

qt_screenshot

Take a screenshot of a specific widget or the entire window to visually inspect UI state.

qt_widget_details

Retrieve detailed properties for a specific widget to understand its state and configuration.

qt_click

Simulate a mouse click on a target widget with optional modifiers and button choice.

qt_type

Type text into a focused widget to simulate user input.

qt_key_press

Send a keyboard event to the application, such as Return, Escape, or Ctrl+S.

qt_set_property

Set a Qt property on a widget to adjust its behavior or appearance.

qt_invoke_slot

Invoke a QObject slot or method to trigger application logic.

qt_list_windows

List all top-level windows currently managed by the application.

qt_object_tree

Retrieve the full QObject parent-child tree for exploration.

qt_scene_snapshot

Enumerate and inspect items within a QGraphicsScene.

qt_vtk_scene_info

Get information about the VTK scene state, including camera and actors.

qt_vtk_screenshot

Capture a render from a VTK scene as an image.