QtGuiTestingMCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
QtGuiTestingMCP
QtGuiTestingMCP is a localhost MCP bridge for testing a running C++ Qt GUI application headlessly. An MCP-enabled agent can discover UI elements, interact with named controls, detect popup errors, inspect Qt logs, capture screenshots, and run readable UI-test scripts.
Local validation is performed on Windows. CI is configured to build and test the project on Windows, Ubuntu, and macOS for pushes, pull requests, and manual workflow dispatches.
The bridge runs inside the Qt GUI process, so widget operations remain on the GUI thread. The Python process is only the MCP adapter and script runner.
Quick start
Build the Debug demo, start it headlessly, and register QtGuiTestingMCP with your agent:
cmake --build build
$env:QT_QPA_PLATFORM = "offscreen"
./build/qtgui-testing-mcp.exe
python scripts/setup_mcp.py --codex --writeReplace --codex with --claude, --opencode, or --cursor. Use --all to
configure all four clients. The setup command previews changes unless
--write is supplied and creates a backup before changing an existing file.
See docs/SETUP.md for client paths and advanced options.
Related MCP server: Qt Pilot
Features
Qt UI-tree discovery using stable
objectNameselectors for QWidget and QWindowButton activation and deterministic text entry
Menu and toolbar
QActiondiscovery and semantic activationKeyboard press/release and mouse move/click/double-click event simulation
Popup error detection for visible
QMessageBoxinstancesRich UI metadata: geometry, focus, accessibility name, text, visibility, active/exposed state, and widget enabled state
Application health/status inspection
Qt debug/info/warning/critical log capture
Qt event-loop settling for asynchronous UI updates
PNG screenshots, automatic per-step screenshots, and file saving
Human-readable UI-test scripts without quotes or JSON structures
Natural-language-to-script workflow through MCP tool descriptions and prompts
Offscreen execution through
QT_QPA_PLATFORM=offscreenQtTest integration coverage through CTest
GitHub Actions validation on Windows, Ubuntu, and macOS
Architecture
AI agent / MCP client <── MCP stdio ──> Python MCP adapter
│ localhost TCP
▼
C++ Qt application
AgentBridge / GUI threadThe C++ application must be started separately. This project intentionally does not launch or terminate the application on behalf of the MCP server.
Requirements
Qt 6 with Gui, Widgets, and Network components
C++17 compiler supported by the selected Qt kit
CMake 3.21 or newer
Ninja or another supported CMake generator
Python 3.11 or newer with the MCP SDK dependency from
requirements.txtA Debug build to enable the bridge, or an explicit
QT_GUI_TESTING_MCP_ENABLE_BRIDGE=ONrelease-package option
The project version is maintained in VERSION and follows
Semantic Versioning.
On Windows, use the Visual Studio 2022 generator so the MSVC compiler and Windows SDK are selected explicitly. Ninja is also supported from a Visual Studio Developer PowerShell with the MSVC environment initialized.
Build
Replace the Qt path with the kit installed on your machine:
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
-DCMAKE_PREFIX_PATH=/path/to/Qt/6.x.x/msvc2022_64 `
-DCMAKE_BUILD_TYPE=Debug `
-DBUILD_TESTING=ON
cmake --build build --config DebugThe bridge is enabled by the project-owned QT_GUI_TESTING_MCP_ENABLED macro in
Debug builds. Release packaging enables it explicitly with the project option;
Qt's internal QT_DEBUG macro is not overridden.
Release binaries
Tagged releases build self-contained archives for Windows, Linux, and macOS. The packages contain the demo executable with its deployed Qt runtime, the Python MCP adapter, setup utility, documentation, and license. Download the archive matching the target platform from the GitHub release instead of installing Qt just to run the demo.
The release workflow validates the tag against VERSION, builds each platform
package, and attaches all archives to the GitHub release.
Run the demo headlessly
# Set this to the Qt kit used by CMake. The Qt bin directory provides the
# runtime DLLs and the plugins directory provides qoffscreen.dll.
$qtRoot = "C:\Qt\6.x.x\msvc2022_64"
$env:PATH = "$qtRoot\bin;$env:PATH"
$env:QT_PLUGIN_PATH = "$qtRoot\plugins"
$env:QT_QPA_PLATFORM = "offscreen"
./build/qtgui-testing-mcp.exeFor a distributable Windows directory, use Qt's deployment tool after the build instead of relying on a developer environment:
& "$qtRoot\bin\windeployqt.exe" `
--dir build\deploy `
build\qtgui-testing-mcp.exeRun build\deploy\qtgui-testing-mcp.exe from that deployed directory.
The demo exposes these selectors:
Object name | Qt class | Purpose |
|
| Main window and screenshot target |
|
| Text input |
|
| Output text |
|
| Button action |
Configure the MCP client
Install the Python dependency:
python -m pip install -r requirements.txtRegister the server with an MCP client using an absolute path:
{
"mcpServers": {
"qt-gui-testing": {
"command": "python",
"args": ["/absolute/path/to/QtGuiTestingMCP/src/qtgui_mcp_server.py"]
}
}
}Restart or reload the MCP client after changing its configuration. The server
uses stdio for MCP and connects to the Qt process at 127.0.0.1:9999.
One-command setup
QtGuiTestingMCP includes a safe setup command for common MCP clients. It previews
the exact file changes by default and creates a timestamped backup when
--write updates an existing file:
python scripts/setup_mcp.py --client claude
python scripts/setup_mcp.py --client claude --writeConfigure Claude Desktop, Codex, OpenCode, and Cursor together:
python scripts/setup_mcp.py --all --writeUse --scope global for a user-level Codex, OpenCode, or Cursor installation,
--name to choose another server key, and --path for a non-standard config
location. Existing unrelated servers are preserved. Use --force only when an
entry with the selected name already exists and should be replaced. See
docs/SETUP.md for platform paths, format details, and the
complete option reference.
Available MCP tools
Tool | Purpose |
| Show the complete script command reference |
| Discover visible QWidget and QWindow elements and selectors |
| Check bridge, window, and log-buffer health |
| Process queued Qt events for a bounded interval |
| Retrieve captured Qt diagnostic messages |
| Clear the in-memory log buffer |
| Activate a |
| Trigger a menu or toolbar |
| Set a |
| Send a keyboard press/release pair |
| Send mouse move, click, or double-click events |
| Inspect visible |
| Return a PNG image to the MCP client |
| Run a bounded line-oriented UI test |
The MCP prompt create_ui_test_script helps clients that expose MCP prompts to
translate a natural-language request into a test script. The MCP server does
not contain a second language model; the agent performs that translation.
Natural-language workflow
Users can describe a test normally:
Test the greeting flow, enter Ada Lovelace, click Say hello, verify the
message, check for popup errors, and save a screenshot to results/greeting.png.The agent should discover selectors, show or summarize the generated script, run it, and report each step plus the final UI state.
UI-test scripts
Scripts use one command per line. Quotes and JSON are not required:
# Greeting workflow
start ui test
status
wait idle 250
type nameEdit Ada Lovelace
click helloButton
assert contains messageEdit Hello, Ada Lovelace!
assert no-errors
logs
save screenshot to results/greeting.png
end ui testAvailable commands include:
start ui test
end ui test
show ui test commands
tree
status
wait idle 250
logs
clear logs
screenshot mainWindow
save screenshot to results/current.png
click helloButton
type nameEdit Ada Lovelace
key nameEdit End
key nameEdit Ctrl+A
mouse click helloButton
mouse double-click helloButton
activate openAction
wait 250
wait-text statusLabel Ready
assert visible helloButton true
assert enabled helloButton true
assert text messageEdit Hello, Ada Lovelace!
assert contains messageEdit Lovelace
assert popup critical Connection refused
assert no-errorsText consumes the rest of a line, so spaces do not require quoting. A PNG is
captured automatically after every command. save screenshot to PATH writes
the most recent buffer; parent directories must already exist.
Scripts stop on the first failed step by default, are limited to 100 steps, and never execute arbitrary Python, shell commands, or application code. See docs/USER_GUIDE.md for the full guide.
Application integration
Include the bridge in the application entry point and construct it after
QApplication:
#ifdef QT_GUI_TESTING_MCP_ENABLED
#include "AgentBridge.h"
#endif
QApplication app(argc, argv);
#ifdef QT_GUI_TESTING_MCP_ENABLED
AgentBridge bridge(9999);
#endifGive agent-facing controls stable, unique names:
loginButton->setObjectName("loginButton");
usernameEdit->setObjectName("usernameEdit");
statusLabel->setObjectName("statusLabel");Tests
Run the QtTest integration suite:
ctest --test-dir build --output-on-failureThe suite uses the offscreen platform and exercises the real localhost JSON/TCP bridge, including widget discovery, interaction, screenshots, popup detection, menu and toolbar actions, QWindow input, validation errors, status, logs, and event-loop settling. Python tests cover setup configuration, script parsing, action lookup, error propagation, and automatic screenshot reporting.
The GitHub Actions workflow runs these checks on Windows, Ubuntu, and macOS. Pushes and pull requests start the matrix automatically; maintainers can also run it from the workflow's Run workflow control.
Troubleshooting
The MCP tools cannot connect
Confirm that the Debug Qt application is already running and listening on
127.0.0.1:9999. Check get_app_status and verify that another process is not
using the port.
The application does not appear in screenshots
Set QT_QPA_PLATFORM=offscreen before launching the application, call
wait_for_idle, and ensure at least one top-level QWidget or QWindow is shown.
On Windows, also ensure the selected Qt kit's bin directory is on PATH and
its plugins directory is available through QT_PLUGIN_PATH; otherwise Qt
may report that it could not initialize the offscreen platform plugin.
A widget cannot be found
Call get_widget_tree and use the exact objectName. Display text is not a
selector, and unnamed widgets are intentionally not reliable targets.
Errors are missing
get_popup_errors recognizes standard QMessageBox dialogs. Custom dialogs
should be inspected with get_widget_tree; application diagnostics emitted via
qDebug, qInfo, qWarning, or qCritical are available through
get_recent_logs.
The C++ build cannot find type_traits or kernel32.lib
The compiler is running without the MSVC/Windows SDK environment. Configure and build from a Visual Studio Developer PowerShell, then rerun CMake.
Security and limitations
The bridge binds only to loopback but still grants local clients control of the application. Keep it disabled in production builds. Do not expose the port remotely without authentication and authorization.
Current limitations include:
application process launch/stop is managed externally;
popup classification is automatic for
QMessageBoxonly;the log buffer is bounded in memory and is not a persistent log store;
screenshots are PNG images saved by the MCP server process; QWindow captures use Qt's associated screen surface. Generic QWindow captures may be unavailable with the offscreen QPA plugin because it has no composited native screen surface; inspection and event delivery still work.
Development
docs/USER_GUIDE.md — user and agent workflow
docs/AGENT_USAGE.md — runtime agent guidance
docs/SETUP.md — setup command and client configuration
docs/DEVELOPMENT.md — project layout and development
docs/RELEASING.md — versioning and release workflow
CONTRIBUTING.md — contribution and validation conventions
LICENSE — MIT license
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Free test management over MCP: projects, test cases, plans, runs, environments and tasks.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
No-code, AI-assisted UI testing: record new tests, run existing ones, and monitor the results.
Run and manage H Company's Computer-Use Agents from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides automated GUI testing and control capabilities through an MCP server that enables mouse movements, keyboard input, screen captures, and image recognition across Windows, macOS, and Linux.48MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for headless Qt/PySide6 GUI testing that enables AI assistants to launch desktop applications via Xvfb and perform visual verification. It supports widget discovery, screenshot capture, and simulated user interactions like clicks, typing, and keyboard shortcuts.9MIT
- AlicenseAqualityBmaintenanceMCP server for automating and introspecting native Qt applications (QWidget and QML) without source changes. Enables AI agents to control running Qt apps through UI snapshots, element lookup, and real input simulation.259MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP agents to run, continue, observe, check status of, and abort bounded GUI automation tasks through a shared local runtime with visual detection and deterministic input.Apache 2.0