List running Qt apps that have the qtpy-mcp probe (Houdini, Blender, Maya, ...).

Shows each instance id, process, binding and visible window titles. Use the id with the instance argument of any tool, or with qt_select_instance.

Make one running Qt app the default target for later tool calls.

Args: instance: Instance id, pid, name, or words from a window title, e.g. "PIPE-1234".

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.

Search the widget tree for widgets matching criteria. Prefer over qt_snapshot.

Two modes. With describe and/or window_title it is a semantic search: describe is matched fuzzily (typos, punctuation and case ignored) against label/button text, group and dock titles, tooltip, what's-this, status tip, accessible name/description, objectName, placeholder, tab titles, dynamic properties, class name and style sheet; results are ranked with the reason each matched. Otherwise the plain substring filters below apply.

Registers found widgets in the ref registry — returned refs are immediately usable with qt_click, qt_type, qt_get_text, etc.

Args: pattern: Case-insensitive substring matched against class name, objectName, or text content (OR logic across fields). class_name: Exact class name, case-insensitive (e.g. 'QLineEdit', 'QPushButton', 'ControlWidget'). Must match the full class name, not a substring. object_name: Substring match on objectName. text: Substring match on widget text/label content. root_ref: Restrict search to subtree of this widget. visible_only: Only return visible widgets (default True). max_results: Cap on results returned (default 20). describe: Free-text description, e.g. 'Name goes here:' or 'save the profile'. window_title: Fuzzy match on the top-level window title (e.g. 'PIPE-1234'). search_fields: Limit describe to some of: text, title, placeholder, tooltip, whats_this, status_tip, accessible_name, accessible_description, object_name, window_title, tab_text, properties, class_name, style_sheet. min_score: Minimum semantic match score 0-1 (default 0.5).

At least one of pattern, class_name, object_name, text, describe or window_title must be provided.

Take a screenshot of a window or any widget, identified by ref OR by description.

Identify the widget semantically instead of by ref, e.g. describe="Name goes here:" (a label: captures the widget that holds it), describe="save the profile" (tooltip), window_title="PIPE-1234" with class_name="QDockWidget" (a docked widget), or object_name="nameEdit". Add instance (pid, id or window title of the app) when several Qt apps are running.

Args: ref: Widget ref from qt_snapshot/qt_find_widget. If nothing identifies a widget, the active window is captured. 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). describe: Free-text description matched against text, titles, tooltip, what's-this, status tip, accessible name, objectName, placeholder, QSS ... (fuzzy). window_title: Fuzzy match on the top-level window title. class_name: Qt class, subclasses match (e.g. 'QDockWidget'). object_name: objectName, supports * and ? wildcards. search_fields: Limit describe to specific fields (see qt_find_widget). expand: What to capture relative to the match: 'auto' (a matched label captures the widget holding it; anything else captures itself), 'self', 'parent', 'buddy' (the label's field) or 'window'. index: Which ranked match to use (0 = best). min_score: Minimum semantic match score 0-1.

Returns an image plus a note saying what was captured.

Record an animated GIF of a window or widget for duration seconds.

Identify the widget exactly like qt_screenshot (ref, or describe/window_title/ class_name/object_name; the active window if nothing is given). The app keeps running normally while recording; interact with it meanwhile via other tools or by hand. Works on Windows and Linux (frames come from Qt's own rendering, no screen capture needed). For longer or interleaved recordings use qt_record_start / qt_record_stop.

Start a background GIF recording; stop it later with qt_record_stop.

Returns a recording id that already names the app, so qt_record_stop needs no instance. Recording stops by itself after max_seconds.

Stop a recording started with qt_record_start and return the GIF.

Args: recording_id: The id returned by qt_record_start (includes the app it belongs to).

Semantic widget search across ALL running Qt apps at once.

Use when you do not know which app has the widget. Each hit names its instance; pass that id as instance to qt_screenshot, qt_click, ... together with the ref.

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.

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.

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. use_clipboard: If True, insert via Ctrl+V paste instead of key-by-key events. Use this for multi-line text in console/terminal widgets — character-by-character typing treats each newline as Enter (submit), corrupting multi-line input.

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.

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.

Invoke a slot or method on a QObject.

Args: ref: Widget ref from qt_snapshot. method_name: Slot/method name to invoke.

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.

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.

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).

Execute multiple Qt operations in a single round trip.

Chains clicks, types, key presses, waits, snapshots, and reads into one server call — dramatically reduces latency compared to sequential tool calls.

Each step dict: method (str, required): RPC method — same names as probe methods: click, type_text, key_press, set_property, invoke_slot, get_text, trigger_action, wait_for, snapshot, find_widget, screenshot. Special: "wait" with params {"ms": N} sleeps N ms processing events. params (dict, optional): Parameters forwarded to the method. wait_ms (int, optional): Extra pause after the step (default 0).

Execution stops on the first error; partial results are returned. Screenshot steps return size only (not base64 data) — call qt_screenshot separately when you actually need the image.

Note: refs must be known before calling qt_batch — steps cannot reference results from earlier steps within the same batch. Use qt_find_widget first to obtain refs, then pass them into the batch call.

Example — click a button twice then read a label in one round trip: qt_batch([ {"method": "click", "params": {"ref": "w5"}}, {"method": "click", "params": {"ref": "w5"}}, {"method": "get_text", "params": {"ref": "w12"}}, ])

Example — type multi-line code into IPython console and wait for output: qt_batch([ {"method": "type_text", "params": {"ref": "w42", "text": "%run /tmp/x.py", "use_clipboard": true}}, {"method": "key_press", "params": {"key": "Return"}}, {"method": "wait", "params": {"ms": 3000}}, {"method": "snapshot", "params": {"max_depth": 4}}, ])

List all top-level windows and their types.

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.

Check for active popup or modal dialog widgets.

Get actions from a QMenu widget.

Args: ref: Ref to a QMenu widget.

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".

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.

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').

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

Get all items in a QGraphicsScene.

Args: ref: Ref to a QGraphicsView widget.

Get VTK scene state from a PyVista/VTK widget.

Args: ref: Ref to a widget containing a VTK render window.

Capture a VTK render window to an image.

Args: ref: Ref to a widget containing a VTK render window.