qinspector-mcp 0.1.1

stdio MCP bridge for Qt apps that embed QInspector

QInspector MCP Server

stdio MCP bridge for Qt apps that embed QInspector. This process listens on TCP; apps connect out as clients (default 127.0.0.1:9876). Up to 8 apps can be connected at once.

Agent  --stdio MCP-->  qinspector-mcp  --TCP-->  Qt app(s) with QInspector

Your Qt app must call QInspector::Connect() and Attach(...). See the main QInspector repository for the C++ library and demos.

Install

Requires uv (recommended) or Python ≥ 3.10.

uvx qinspector-mcp

Other options:

# from Git
uvx --from "git+https://github.com/DebiruC/QInspector.git#subdirectory=mcp" qinspector-mcp

# from a local clone
uvx --from /path/to/QInspector/mcp qinspector-mcp

# pip
pip install qinspector-mcp
qinspector-mcp

Only one process may bind the configured port (default 9876).

MCP host config

Add to Claude Code, Cursor, or any host that supports MCP stdio servers:

{
  "mcpServers": {
    "qinspector": {
      "command": "uvx",
      "args": ["qinspector-mcp"],
      "env": {
        "QINSPECTOR_HOST": "127.0.0.1",
        "QINSPECTOR_PORT": "9876",
        "QINSPECTOR_RPC_TIMEOUT": "10"
      }
    }
  }
}

From Git instead of PyPI:

{
  "mcpServers": {
    "qinspector": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/DebiruC/QInspector.git#subdirectory=mcp",
        "qinspector-mcp"
      ],
      "env": {
        "QINSPECTOR_HOST": "127.0.0.1",
        "QINSPECTOR_PORT": "9876"
      }
    }
  }
}

From a local checkout, point --from at your mcp directory (forward slashes work on Windows):

{
  "mcpServers": {
    "qinspector": {
      "command": "uvx",
      "args": ["--from", "/path/to/QInspector/mcp", "qinspector-mcp"],
      "env": {
        "QINSPECTOR_HOST": "127.0.0.1",
        "QINSPECTOR_PORT": "9876"
      }
    }
  }
}

No cwd or PYTHONPATH is required when using uvx.

Usage

1. Start the MCP server (host config or uvx qinspector-mcp).
2. Start your Qt app so it connects and sends session.hello.
3. Call list_sessions, then tools with the session name (for example main-window or qtquick-main in the demos).

App identity

Each app sends app.hello with appId (default QCoreApplication::applicationName()) and pid. The bridge keys apps by appId; duplicates become editor#2, etc. Apps that never send app.hello get app-N.

Pass the optional tool argument app only when the same session name exists on more than one connected app (the error message lists candidates).

Tools

Tool	Purpose
list_sessions	Connected apps and their sessions
ping	Health check on a session
ui_tree	UI tree under the Attach root (compact; qt_* chrome hidden by default)
ui_properties	Read properties of the root or a named descendant
ui_set	Write one property (requires SetInputInjectionEnabled(true) in the app)
ui_find	Search the full tree by class / objectName / text
ui_screenshot	Screenshot at original size (MCP image, or save_path to disk)
ui_click / ui_drag / ui_wheel / ui_type	Synthetic input (requires injection enabled)
app_logs	Captured qDebug / QML logs (requires SetLogCaptureEnabled(true))
wait_for	Poll a property until it matches (MCP-side; no extra RPC)
raw_call	Raw JSON-RPC (only if QINSPECTOR_MCP_ALLOW_RAW=1)

Environment

Variable	Default	Meaning
QINSPECTOR_HOST	127.0.0.1	Listen address
QINSPECTOR_PORT	9876	Listen port
QINSPECTOR_RPC_TIMEOUT	10	Seconds to wait for an app response
QINSPECTOR_MCP_ALLOW_RAW	off	Enable raw_call

License

MIT