Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qt-mcp screenshot of 'Calculator' window"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for inspecting Qt applications through screenshots and performing basic filesystem operations.
qt-mcp 0.3.0 lets an MCP-capable AI client see a Qt or desktop application, inspect complete windows, selected regions, or named widgets, and read or update nearby project files. It uses the MCP Python SDK v1.28.1 high-level FastMCP API and stdio transport. The architecture is inspired by VibeUE, adapted for Qt and general desktop windows.
Enumerate visible top-level windows and their geometry.
Capture a whole window by exact or partial title.
Capture an absolute screen rectangle or a rectangle relative to a window.
Capture a named QWidget precisely through the standalone proxy/agent or the embedded server.
Let the standalone server wait for an agent-enabled Qt app to attach over a Unix domain socket.
Return screenshots directly as PNG image content to the MCP client.
Read and write text files.
List and create directories.
Move, rename, and delete files or directory trees.
Inspect file metadata.
Search recursively by glob or regular-expression content.
See the complete tool reference for exact signatures and return shapes.
Related MCP server: qt-mcp
Platform | Window enumeration | Screen grab | Extra system dependency |
Linux/X11 |
|
|
|
Windows | Win32 |
| None |
Wayland and macOS are not currently supported by the OS-level window-discovery path. Linux also has an optional ImageMagick import fallback if mss cannot grab the display.
Python 3.10 or newer.
An active desktop session.
Linux: an X11 session with DISPLAY set, plus wmctrl or xwininfo from x11-utils.
Windows: no additional system package.
On Debian or Ubuntu:
sudo apt install wmctrl
# Alternatively: sudo apt install x11-utilsFrom the repository root:
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m qt_mcp.serverOn Windows PowerShell:
py -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
.venv\Scripts\python.exe -m qt_mcp.serverThe installed console script is also available as .venv/bin/qt-mcp on Linux or .venv\Scripts\qt-mcp.exe on Windows. The server uses stdin and stdout for MCP JSON-RPC, so it normally should be launched by an MCP client rather than an interactive terminal.
A Qt app can remain a normal application and opt into exact widget capture with one call:
from qt_mcp.agent import start_agent
agent = start_agent(window)The MCP client launches standalone qt_mcp.server, which listens on /tmp/qt-mcp-<uid>.sock on Linux/macOS or the qt-mcp-<username> named pipe on Windows, then proxies capture_widget(widget_name) to the attached app's GUI thread. See the complete proxy/agent integration recipe.
Claude Code, Cursor, Antigravity, and other stdio MCP clients use the same command-and-arguments pattern. Put the server entry in the client's MCP configuration file; the exact configuration-file location varies by client.
Use the absolute path to the virtual environment's Python executable. GUI clients often start with a restricted PATH, so relying on python or qt-mcp being globally discoverable is fragile.
{
"mcpServers": {
"qt-mcp": {
"command": "/home/you/projects/Gui Editor MCP/.venv/bin/python",
"args": ["-m", "qt_mcp.server"]
}
}
}{
"mcpServers": {
"qt-mcp": {
"command": "C:/Users/you/projects/Gui Editor MCP/.venv/Scripts/python.exe",
"args": ["-m", "qt_mcp.server"]
}
}
}Forward slashes avoid JSON backslash escaping on Windows. A Linux template is also available in mcp-config.example.json.
Mode | Process model | Tools | Widget capture | Best for |
Standalone OS capture, | Separate stdio server observes desktop windows | 15 | OS-level windows and regions | Zero-change setup and quick inspection |
Standalone proxy + Qt agent | The same standalone server proxies to one attached Qt app | 15 | Real | Reusable server plus a normal independently launched Qt app |
In-process example, | Qt app embeds FastMCP in a background thread | 14 | Real | Tight coupling where the app itself is the MCP server |
The standalone server always advertises 15 tools; its three proxy tools start the platform transport lazily and require an attached agent for widget operations. OS-level mode requires no target-app changes. Proxy and in-process modes both capture occluded or off-screen widgets precisely. Follow the integration guide, and see the implementations in src/qt_mcp/agent.py and examples/qt_editor/.
# 1. Find the Qt app window
list_windows()
# -> {"windows": [{"id": "0x038...", "title": "My Qt App — main.cpp", ...}], ...}
# 2. Capture the whole window (the vision model receives the PNG)
capture_window(title="My Qt App")
# 3. Capture a panel relative to that window
capture_region(title="My Qt App", x=10, y=40, width=400, height=300)
# 4. Save inspection notes through the filesystem tools
write_file(path="/tmp/notes.md", content="Top panel shows the toolbar...")This screenshot-to-inspection-to-filesystem loop lets the client correlate the rendered interface with the files that produce it.
.
├── docs/
│ ├── ARCHITECTURE.md
│ ├── DEVELOPMENT.md
│ ├── INTEGRATION.md
│ └── TOOLS.md
├── examples/
│ ├── qt_editor/
│ │ ├── __init__.py
│ │ ├── editor_window.py
│ │ ├── main.py
│ │ └── mcp_server.py
│ └── qt-editor.mcp-config.example.json
├── src/qt_mcp/
│ ├── __init__.py
│ ├── agent.py
│ ├── agent_proxy.py
│ ├── filesystem.py
│ ├── protocol.py
│ ├── screenshots.py
│ └── server.py
├── tests/
├── mcp-config.example.json
├── pyproject.toml
└── README.mdTool reference — exact signatures, parameters, return shapes, and calls for all standalone and in-process tools.
Integration guide — how to use OS-level capture, attach an agent to the standalone proxy, or embed a server in your Qt app.
Architecture — capture pipeline, module responsibilities, concurrency model, dependencies, and errors.
Development — contributor setup, manual stdio testing, adding tools, platform checks, and releases.
Add Wayland OS-level capture through platform-appropriate tools or portals.
Add macOS window discovery and capture.
Generalize CaptureBridge into a reusable package component.
Add configurable screenshot persistence.
Expand automated platform and protocol tests.
MIT
Check whether a Qt app is currently attached via the proxy agent.
Always works, no error. Useful for clients to poll.
Returns: {"attached": bool, "socket_path": str}.
Inputs: no named parameters.
Capture a rectangular screen region as a PNG image.
Args:
x: Top-left X. Absolute screen coordinate, or relative to the window
identified by title when that is given.
y: Top-left Y. Absolute screen coordinate, or relative to the window
identified by title when that is given.
width: Region width in pixels.
height: Region height in pixels.
title: Optional window title. When set, x/y are treated as offsets from
that window's top-left corner (use list_windows to find the title).
Returns the region as a PNG image.
Inputs: x (required), y (required), width (required), height (required), +1 more.
Capture a specific Qt widget by its objectName via the proxy agent.
Requires a Qt application that has called qt_mcp.agent.start_agent(window)
and is connected to this server's Unix domain socket.
Args:
widget_name: The widget's objectName. Use list_capturable_widgets
to discover valid names.
Returns the widget as a PNG image.
Inputs: widget_name (required).
Capture an entire window identified by its title (case-insensitive substring match).
Args: title: Window title or substring of it (case-insensitive). Use list_windows to find candidates. When multiple windows match, the call fails and lists the matching titles — provide a more specific substring or set exact=True. exact: If True, match the title exactly (case-sensitive).
Returns the screenshot as a PNG image. The window's geometry is logged but not returned alongside the image (call list_windows for geometry details).
Inputs: title (required), exact.
Create a directory.
Args:
path: Directory path to create. ~ is expanded.
parents: Create parent directories as needed (default True).
Returns: path, created, exists.
Inputs: path (required), parents.
Delete a file or directory.
Args: path: Path to delete. Symlinks are unlinked (their targets are preserved). recursive: Required True to delete a directory tree. Files are deleted regardless of this flag.
Returns: path, deleted.
Inputs: path (required), recursive.
Return metadata for a file, directory, or symlink.
Returns: path, type, size, modified (ISO-8601 UTC), is_symlink, permissions.
Inputs: path (required).
List the objectNames of widgets in the attached Qt app.
Requires a Qt application that has called qt_mcp.agent.start_agent(window)
and is connected to this server's Unix domain socket.
Returns: {"widgets": ["name1", ...], "count": N}.
Inputs: no named parameters.
List entries in a directory.
Args:
path: Directory path (default: current directory). ~ is expanded.
include_hidden: Include dotfiles/dotdirs (default False).
Returns: path, entries (name/path/type/size), count.
Inputs: path, include_hidden.
List all visible top-level X11 windows with id, title, and geometry.
Use this first to discover the exact window title you need for capture_window or capture_region. Each entry has: id, title, desktop, x, y, width, height.
Inputs: no named parameters.
Move or rename a file or directory.
Args: path: Source path. destination: Destination path. overwrite: Overwrite destination if it exists (default False; errors otherwise).
Returns: source, destination, moved.
Inputs: path (required), destination (required), overwrite.
Read a text file. Returns up to limit lines starting at line offset (1-indexed offset, line 1 = offset 0).
Args:
path: File path (absolute, or relative to the server's working dir). ~ is expanded.
offset: Line number to start at (0 = first line). Use this to page through large files.
limit: Maximum number of lines to return (default 2000).
Returns: path, content, total_lines, returned_lines, offset, truncated.
Inputs: path (required), limit, offset.
Search file contents for a regex pattern (recursive).
Args:
path: Directory (or single file) to search.
pattern: Regex pattern to search for (required).
include_hidden: Include dotfiles (default False).
file_glob: Only search files matching this glob (default *, all files).
case_sensitive: Case-sensitive match (default False).
max_matches: Cap on number of result lines (default 100).
context_lines: Lines of context to include around each match (default 0).
Returns: path, pattern, file_glob, matches, count, files_scanned, truncated.
Inputs: path, pattern, file_glob, max_matches, +3 more.
Find files matching a glob pattern (recursive).
Args:
path: Directory to search in (default current dir).
pattern: Glob pattern, e.g. **/*.py, *.txt, src/**/*.json.
include_hidden: Include dotfiles (default False).
max_results: Cap on number of matches (default 500).
Returns: path, pattern, matches, count, truncated.
Inputs: path, pattern, max_results, include_hidden.
Write or append text to a file.
Args:
path: Destination file path. ~ is expanded.
content: Text content to write.
append: If True, append to the file instead of overwriting.
create_parents: Create parent directories if they do not exist.
Returns: path, bytes_written, appended.
Inputs: path (required), content (required), append, create_parents.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
Each tool has a clearly distinct purpose: file operations (move, create_directory, read_file, write_file, etc.) are separate from screen capture tools (list_windows, capture_window, capture_region) and Qt widget tools (capture_widget, list_capturable_widgets, attach_status). There is no overlap or ambiguity between tools.
Most tool names follow a verb_noun pattern (e.g., create_directory, list_windows, read_file). However, a few deviate: 'delete' is a single verb, and 'file_info' is noun_noun. Overall the pattern is mostly consistent and intuitive.
15 tools is slightly above the typical range but still well-scoped for the server's three domains (file management, screen capture, Qt widget capture). The count is justified and not excessive.
File operations cover create, read, update, delete, list, search, and move—nearly complete lifecycle. Screen capture tools provide listing and capture. Qt widget tools offer listing and capture but lack interaction beyond capture, which is acceptable given the server's focus.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
