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

Environment

License

MIT