GammaRay MCP Bridge

A MCP server that bridges GammaRay probe introspection data into MCP tools, enabling LLMs to inspect and debug Qt Quick / QML scene graphs, items, geometry, materials, and Qt Widgets.

Architecture

Target Qt/QML App  ──TCP──►  GammaRay MCP Bridge  ──stdio──►  LLM / AI Agent
  (GammaRay probe                (GammaRay client +               (opencode,
   injected)                      qtmcp MCP server)                ZCode, etc.)

The bridge is a GammaRay client: it connects to a probe injected into a target Qt app, reads the same models the GammaRay GUI uses, and translates them into MCP JSON-RPC tool calls over stdio. Supports both QML Quick apps (SceneGraph, QML items) and Qt Widget apps (widget hierarchy, properties, attributes).

Related MCP server: gdb and rr Debugging

Prerequisites

• Qt 6.8+ (system)

• C++20 compiler (GCC 12+, Clang 16+)

• GammaRay 3.4.0+ (system package: gammaray-dev on Debian/Deepin)

• qtmcp (consumed via FetchContent — no manual install)

• Python 3.10+ with pytest (for running the test suite)

Building

1. Install system dependencies

# Debian / Deepin
sudo apt install gammaray-dev gammaray-plugin-quickinspector

2. Build the bridge

cd bridge
cmake -S . -B build -G Ninja
cmake --build build

Offline build (using a local qtmcp clone)

If you have a local clone of qtmcp (e.g. at /home/user/Sources/qtmcp), pass FETCHCONTENT_SOURCE_DIR_QTMcp to skip the network fetch:

cd bridge
cmake -S . -B build -G Ninja \
  -DFETCHCONTENT_SOURCE_DIR_QTMcp=/home/user/Sources/qtmcp \
  -DFETCHCONTENT_FULLY_DISCONNECTED=ON
cmake --build build

3. Run

# Start a probe (inject into a QML app)
gammaray --inject-only --listen tcp://127.0.0.1:11732 \
  --injector preload /usr/lib/qt6/bin/qml /path/to/app.qml -platform offscreen

# Or inject into a widget app
gammaray --inject-only --listen tcp://127.0.0.1:11732 \
  --injector preload /path/to/widget-app

# Start the bridge (stdio MCP server)
bridge/run.sh

The bridge starts in lazy-connect mode. Call connectProbe("127.0.0.1", 11732) from your MCP client once the probe is up.

4. Build a .deb package (optional)

cd bridge/build
cpack -G DEB

The package installs the bridge binary (/usr/bin/gammaray-mcp-bridge), qtmcp shared libs and plugins, and the run.sh helper script. System dependencies (gammaray >= 3.4.0, Qt6 libs) are auto-detected.

MCP Tools

Connection management

QML Navigation

QML Item inspection

SG Node inspection

Rendering visualization

Widget inspection

Testing

# QML test suite (requires a QML app probe):
./tests/run_tests.sh

# Widget test suite (requires a widget app probe):
./tests/run_widget_tests.sh

# Unit tests only:
./tests/run_tests.sh --no-probe

See tests/README.md for details.

License

GPL-2.0-or-later. The bridge links GammaRay libraries (GPL-2.0-or-later) and uses qtmcp (available under LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only — we comply under GPL-2.0-only).