Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| QT_MCP_HOST | No | Probe TCP host (used by the MCP server to connect to the probe). | localhost |
| QT_MCP_PORT | No | Probe TCP listen port. | 9142 |
| QT_MCP_PROBE | No | Set to 1 to auto-activate the probe in the target application. |
Capabilities
Features and capabilities supported by this server
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| qt_snapshot | Capture the full Qt widget tree as a structured accessibility-like snapshot. Returns a YAML-like text tree with widget types, object names, text content, geometry, visibility, enabled state, and interaction refs (w1, w2, ...). Use the refs to interact with specific widgets via other tools. |
| qt_screenshot | Take a screenshot of the entire window or a specific widget. Args:
ref: Widget ref from qt_snapshot (e.g., 'w5'). If omitted, captures active window.
full_window: If True, captures the first visible top-level window.
max_width: Max width before downscaling (default 1920).
max_height: Max height before downscaling (default 1080).
format: Image format - 'png' or 'jpeg' (default 'png').
quality: JPEG quality 1-100 (default 80, ignored for PNG).
Returns a base64-encoded PNG image. |
| qt_widget_details | Get detailed properties of a specific widget. Args:
ref: Widget ref from qt_snapshot (e.g., 'w5').
Returns all Qt properties, geometry, parent chain, and more. |
| qt_click | Click a widget. Args:
ref: Widget ref from qt_snapshot.
button: Mouse button - 'left', 'right', or 'middle'.
modifiers: Keyboard modifiers - 'shift', 'ctrl', 'alt', 'meta'.
position: [x, y] relative to widget top-left. Default: center. |
| qt_type | Type text into a widget. Args:
ref: Widget ref from qt_snapshot.
text: Text to type.
clear_first: If True, select all and delete before typing. |
| qt_key_press | Send a key event to a widget or the focused widget. Args:
key: Key name (e.g., 'Return', 'Escape', 'Ctrl+S', 'a').
ref: Widget ref. If omitted, sends to the currently focused widget. |
| qt_set_property | Set a Qt property on a widget. Args:
ref: Widget ref from qt_snapshot.
property_name: Qt property name.
value: New value for the property. |
| qt_invoke_slot | Invoke a slot or method on a QObject. Args:
ref: Widget ref from qt_snapshot.
method_name: Slot/method name to invoke. |
| qt_get_text | Extract text content from a text editor or input widget. Args:
ref: Widget ref from qt_snapshot (e.g., 'w5').
Works with QPlainTextEdit, QTextEdit, QLineEdit, QLabel, QComboBox,
and any widget with a text() or toPlainText() method. |
| qt_trigger_action | Trigger a menu action or toolbar action by text or index. Args:
ref: Ref to a QMenu, QMenuBar, QToolBar, or any widget with actions.
action_text: The action's display text (e.g., 'Save', '&Open').
Ampersands are stripped for matching.
action_index: The 0-based index of the action
(matching qt_menu_items order).
Provide either action_text or action_index (not both).
Use qt_menu_items first to see available actions. |
| qt_wait_for | Wait for a UI state change. Args:
condition: One of 'widget_visible', 'window_count_changed', 'property_equals'.
timeout_ms: Max time to wait in milliseconds (default 5000).
object_name: Widget objectName (for widget_visible).
ref: Widget ref (for property_equals).
property_name: Property name (for property_equals).
value: Expected value (for property_equals). |
| qt_list_windows | List all top-level windows and their types. |
| qt_object_tree | Get the full QObject parent-child tree (not just visible widgets). Args:
root_ref: Starting ref. Defaults to QApplication root.
max_depth: Maximum traversal depth. |
| qt_active_popup | Check for active popup or modal dialog widgets. |
| qt_menu_items | Get actions from a QMenu widget. Args:
ref: Ref to a QMenu widget. |
| qt_messages | Returns all console messages Args:
level: Level of the console messages to return. Each level includes the messages
of more severe levels. Defaults to "info". |
| qt_thread_check | Check thread affinity of all QObjects to detect threading issues. Reports which threads own QObjects, flags QWidget subclasses on non-GUI threads (the #1 cause of GUI freezes), and lists QThread instances. |
| qt_signals | Inspect signal connections on a QObject. For a given widget/object, enumerates all signals and reports which are
connected and how many receivers each has. Useful for debugging "nothing
happens when I click" problems.
Args:
ref: Widget ref from qt_snapshot (e.g., 'w5'). |
| qt_layout_check | Detect layout issues in the visible widget tree. Scans all visible widgets and reports problems like:
- zero_size: Visible widget with 0x0 geometry (collapsed)
- no_layout: Container with visible children but no layout manager
- smaller_than_hint: Widget smaller than its sizeHint (content likely clipped)
- text_truncated: Text content wider than widget width
- overlapping_siblings: Sibling widgets with intersecting geometries |
| qt_scene_snapshot | Get all items in a QGraphicsScene. Args:
ref: Ref to a QGraphicsView widget. |
| qt_vtk_scene_info | Get VTK scene state from a PyVista/VTK widget. Args:
ref: Ref to a widget containing a VTK render window. |
| qt_vtk_screenshot | Capture a VTK render window to an image. Args:
ref: Ref to a widget containing a VTK render window. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |