1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qt-mcp Scaffold a Qt mainwindow project called demo" 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.

qt-mcp

by fan1959

Overview Schema Source Related Servers Discussions Admin

Python

qt-mcp

一个本地 stdio MCP 服务器，把 Qt 5.14.2 + MinGW 工具链封装成 148 个 Python 工具，让 Claude 或任何 MCP 兼容客户端可以直接搭建、构建、运行、测试、格式化、部署、检查 Qt C++ 项目，不用离开对话。

概述：本项目把 Qt 5.14.2 工具链（qmake / mingw32-make / windeployqt / moc / lupdate / qmllint / clang-format / cppcheck / signtool / cc / git 等）封装成 148 个 MCP 工具，覆盖 Qt 项目的完整生命周期。MIT 协议，当前版本 v0.4.4。

Python License: MIT Version MCP Tools

项目特点

148 个工具覆盖 Qt C++ 项目完整生命周期（脚手架 → 构建 → 运行 → 测试 → 静态分析 → 主题样式 → 部署签名 → 数据库 → 网络 → 多媒体 → 部署分发 → 游戏状态 → 信号槽 → Q_PROPERTY → Git → 文档 i18n → 运行时 IDE → 构建系统）
本地 FTS5 全文检索：把 Qt 5.14.2 自带的 6613 页文档建成索引，100 ms 内搜到答案
AI 友好的诊断信息：qt_build 把编译器 / moc / uic / 链接器输出解析成结构化 JSON，并给出可执行的修复建议
完整的 e2e 测试：577+ pytest 测试，每个工具配套 happy path + error path + edge case 验证
零样例代码污染：所有 Qt 二进制（*.exe / *.dll）走 subprocess 调真实 Qt SDK，不引入 C++ 源码

Related MCP server: ladder-mcp

V0.4.4 新增 1 个工具

工具	作用
`qt_palette_gen`	生成 QPalette C++ 代码（light/dark 主题），设置 11+ 个 QPalette 角色（Window/Base/Text/Highlight/Disabled 等）。配对 `qt_theme_gen` (QSS) 实现系统级 + per-widget 完整 theming。

详见 CHANGELOG.md。

5 分钟上手

前置条件

Windows 10 / Windows 11
Qt 5.14.2 已装（默认路径 E:\Download_tools\QT\5.14.2\mingw73_64）
Python ≥ 3.10
MinGW 730_64 已装

安装

git clone https://github.com/fan1959/qt-mcp.git
cd qt-mcp
pip install -e .

配到 Claude Code

在 ~/.claude.json 或 MCP 客户端配置里加：

{
  "mcpServers": {
    "qt-mcp": {
      "command": "python",
      "args": ["-m", "server"]
    }
  }
}

第一次使用

重启 Claude Code，在对话里说：

帮我用 Qt 写一个 hello world 项目

Claude 会调 qt_scaffold 生成项目骨架，再调 qt_build + qt_run 编译运行。整个过程你看着终端输出 + Claude 的解释，不用手动跑命令。

Qt 路径自定义

如果 Qt 不在默认路径，设环境变量：

set QT_MCP_QT_ROOT=D:\Qt\5.14.2\mingw73_64    # Windows
export QT_MCP_QT_ROOT=/opt/Qt/5.14.2/gcc_64   # Linux

148 个工具完整清单

快速查找：不确定用什么工具？调 qt_cheatsheet 即可拿到按类别分组的完整 quick reference（每次 sprint 加新工具时自动同步）。下面是这个清单的离线版本。

按 17 个类别组织。每条带一句话说明 + 与其他工具的关系。

1. 脚手架 / 生成器（14）—— 从零创建 Qt 项目

工具	用途
`qt_scaffold`	13 个模板（widget / mainwindow / dialog / qml_app / console_app / tictactoe_game / breakout_game / tasklist / music_player / cards_game / chess_game / generic_game / game_framework）。首选创建项目骨架。
`qt_template_scaffold`	自然语言描述 → 自动选模板（中文/英文关键词匹配）。更适合 LLM 调用：直接说"做个井字棋"即可。
`qt_class_wizard`	生成单个 QObject 子类的 .h/.cpp/.ui 三件套。用于向现有项目加类。
`qt_viewmodel_gen`	MVVM ViewModel（Q_PROPERTY + Q_INVOKABLE + signals），配 QML 用。
`qt_model_gen`	QAbstractListModel / QAbstractTableModel 子类，棋牌数据层。
`qt_qml_component_gen`	6 种 QML 组件（card / board / player / hand / deck / tile），含 qmldir。
`qt_qtquick_3d_setup`	Qt 3D 项目骨架（4 模板：cube / sphere / scene / model_loader）。
`qt_graphics_view_scaffold`	QGraphicsScene + QGraphicsView 教学项目（含拖拽）。
`qt_cpp_tutorial_scaffold`	SCU C++ 强化 9 章 12 个 topic 的 .cpp 教学片段。纯 C++ 无 Qt。
`qt_module_split_init`	把平面 .pro 拆成 lib/ + app/（TEMPLATE=subdirs）。`plan_only=True` 默认。
`qt_module_split_cmake`	CMake 版本的 lib/app 拆分。
`qt_pro_lint`	.pro 文件 12 条 lint 规则（重复 SOURCES、Qt 模块 typo、TEMPLATE 缺失等）。
`qt_pro_edit`	读写 .pro 变量（list/get/set/append/remove）。用于批量改 .pro。
`qt_pro_project_graph`	扫描 .pro 引用 + #include，emit Graphviz DOT 依赖图。

2. 构建（6）

工具	用途
`qt_build`	qmake + mingw32-make + 结构化 JSON 诊断。最常用。
`qt_build_diagnostics`	读 .qt_mcp_last_build.log 解析成 JSON（不重编译）。
`qt_clean`	移除 build artifacts（debug/ release/ moc_.cpp/ ui_.h 等）。
`qt_shadow_build_setup`	build-debug/ + build-release/ + .pro.user + build_shadow.bat。
`qt_build_cache`	ccache / sccache 检测 + 注入 QMAKE_CXX = ccache g++（5-10× 加速）。
`qt_watch`	auto-rebuild on file change（watchdog）。

3. 运行 / 性能（4）

工具	用途
`qt_run`	启动 .exe（foreground 或 detached GUI）。配 qt_kill_exe。
`qt_run_trace`	QT_LOGGING_RULES=*=true 捕获 trace 日志。
`qt_perf_budget`	启动延迟预算（first_cpu + first_window）。CI gate：是否在 budget_ms 内启动。
`qt_perf_compare`	与 baseline JSON 对比。CI gate：是否比上次慢 >regression_ms。

4. 测试（6）

工具	用途
`qt_test`	QTestLIB C++ test exe + 解析 PASS/FAIL。
`qt_qml_test`	qmltestrunner + 解析 TestCase 输出。
`qt_test_fuzz`	libFuzzer skeleton（MinGW 需 clang++）。
`qt_sanitizer_run`	ASan / UBSan / TSan 集成。
`qt_coverage`	gcov + lcov → HTML 报告。
`qt_test_coverage_diff`	两个 lcov .info 对比覆盖率回归。

5. 静态分析 / Lint（15）

工具	用途
`qt_lint`	cpplint + qmllint + clang-tidy 一站式。
`qt_analyze`	clang-tidy 自定义检查（bugprone-/performance-）。
`qt_clazy_check`	Qt 反模式 regex 检查（无 clazy 二进制依赖）。
`qt_cppcheck`	cppcheck --json + Qt library。
`qt_complexity_lint`	McCabe 圈复杂度 per function（threshold 默认 12）。
`qt_format` / `qt_format_check`	clang-format 修 / 审计。
`qt_documentation_lint`	doxygen 注释覆盖率（@brief/@param/@return）。
`qt_async_await_lint`	QtConcurrent / QFuture / QThreadPool 7 条反模式。
`qt_concurrency_lint`	QObject 跨线程并发 8 条规则。
`qt_thread_affinity_check`	QObject 跨线程信号连接 4 条规则。
`qt_qml_lint`	qmllint 包装。
`qt_qml_perf_lint`	QML 运行时性能 6 条规则。
`qt_qml_property_linter`	QML property 静态分析（unused/shadowed/mismatch）。
`qt_layout_check`	.ui XML 布局反模式（5 条规则）。
`qt_accessibility_check`	C++ 源码 a11y 扫描（缺 setAccessibleName / setObjectName 等）。

6. 信号与槽 / QObject（6）

工具	用途
`qt_signal_slot_trace`	connect()/signals/slots 静态分析（text/json/dot）。
`qt_signal_disconnect_check`	找无配对 disconnect 的 connect site（生命周期泄漏）。
`qt_signal_lint_fix`	自动修 4 类反模式（unique_connection/queued_connection/functor_to_pointer/orphan_slot_stub）。
`qt_qobject_invoke_metadata`	静态 QObject 反射（signals/slots/Q_INVOKABLE/Q_PROPERTY）。
`qt_qobject_invoke_property_diff`	对比两 header set 的 QObject metadata 漂移。
`qt_qobject_invocation_count` / `_history` / `_connect_monitor`	invokeMethod 调用计数 / 运行时 history / connect 拓扑热图。

7. Q_PROPERTY / Runtime 反射（5）

工具	用途
`qt_property_browser`	提取 Q_PROPERTY 渲染为 markdown/html/json 表。
`qt_hotreload_check`	Q_PROPERTY 完整性（missing_notify / signal_not_found 等 7 条）。
`qt_invoke_helper_gen`	生成 Qt helper .exe（QApplication + QObject + JSON 协议）。
`qt_qproperty_set`	运行时通过 helper set Q_PROPERTY。
`qt_meta_invoke`	运行时通过 helper invoke Q_INVOKABLE。

8. 主题 / 样式（3）

工具	用途
`qt_theme_gen`	QSS 完整 stylesheet（light/dark）。
`qt_qstyle_sheet_gen`	QSS 14 个 widget selector 子集。
`qt_qss_inspect`	解析 .qss 报告 selector / property / 重复。
`qt_palette_gen`	QPalette C++ 代码生成（light/dark）。配 qt_theme_gen 做完整 theming。

9. 多媒体 / 资源（5）

工具	用途
`qt_audio`	音频 list/probe/play snippet（QSoundEffect / QMediaPlayer）。
`qt_audio_convert`	ffmpeg 批量转 mp3/opus/wav/ogg/flac。
`qt_ico_create`	多分辨率 .ico from PNG（16/32/48/64/128/256）。
`qt_multimedia_setup`	QtMultimedia 启动项目（QMediaPlayer + QSoundEffect + QVideoWidget + .qrc）。
`qt_svg_to_png`	SVG → PNG 多宽度（cairosvg + ImageMagick）。

10. 数据库（7）

工具	用途
`qt_db_seed`	创建 SQLite schema + seed data + CRUD 示例。
`qt_db_validate`	FK integrity + orphan-row scan + integrity_check。
`qt_db_dump`	SQLite → CSV/JSON/SQL dump。
`qt_db_perf_index`	索引建议器（EXPLAIN QUERY PLAN + CREATE INDEX SQL）。
`qt_db_schema_diff`	两个 .db schema 对比 + migration SQL。
`qt_db_open_in_gui`	SQLiteStudio 集成（QT_MCP_DBGUI_EXE 覆盖）。
`qt_mysql_setup`	Qt + MySQL/MariaDB starter + SETUP.md（关键：Qt 5.14 MinGW 不带 QMYSQL）。

11. 网络（3）

工具	用途
`qt_network`	QTcpSocket / QTcpServer / QUdpSocket / QWebSocket 类骨架。
`qt_http_client_gen`	QNetworkAccessManager HTTP 客户端（GET/POST + async/sync）。
`qt_ftp_client_gen`	QNetworkAccessManager FTP 客户端（替代被移除的 QFtp）。

12. 文档 / i18n（7）

工具	用途
`qt_docs_search`	FTS5 全文搜本地 Qt 5.14.2 文档（100ms 内）。
`qt_docs_gen`	生成 Doxyfile + doxygen 运行。
`qt_documentation_auto_fill`	LLM 补 doxygen @brief/@param/@return（dry_run 默认）。
`qt_translate`	lupdate + lrelease 完整流程。
`qt_translation_validate`	.ts 翻译覆盖率（每语言 finished/total）。
`qt_translation_sync`	源 tr() vs .ts 同步（找 missing/orphan）。
`qt_translation_auto_fill`	LLM 填 .ts unfinished 条目（dry_run 默认）。

13. 部署 / 分发（9）

工具	用途
`qt_deploy`	windeployqt 打包 DLL。
`qt_deploy_bundle`	一站式：windeployqt + signtool + NSIS installer 串联。
`qt_signature` / `qt_signature_batch`	signtool.exe 单文件 / 批量签名。
`qt_installer_gen`	NSIS / Inno Setup 脚本 + build_installer.bat。
`qt_cmake_install`	CMake install() + CPack NSIS + windeployqt 集成。
`qt_appx`	Microsoft Store (MSIX/AppX) 打包。
`qt_steamworks_init`	Steamworks SDK 集成骨架（SteamAPI_Init + Achievements）。
`qt_itch_butler`	itch.io .itch.toml + butler push 脚本。

14. 环境 / SDK（6）

工具	用途
`qt_env`	展示 Qt / MinGW 路径 + 版本。
`qt_diagnose_env`	健康检查（16+ 二进制 + 32/64-bit + PATH）。
`qt_pkg`	列已装 Qt 5 模块（headers/libs/plugins）。
`qt_pkg_install`	aqtinstall 装 / 卸 Qt SDK。
`qt_env_diff`	两个 Qt SDK 安装对比（qmake 版本 + 模块差异）。
`qt_dll_search_path`	分析 .exe DLL 搜索路径（找缺失 Qt5*.dll）。

15. 文件 / 资源（6）

工具	用途
`qt_validate`	.pro SOURCES/HEADERS/FORMS/RESOURCES 引用完整性。
`qt_diff`	两个 .pro 项目对比（变量 + SHA1）。
`qt_gen_qrc`	扫描图片目录 → emit .qrc。
`qt_assets`	高级 .qrc + 可选 Q_INIT_RESOURCE cpp。
`qt_resources`	.qrc 增删改查（list/add/remove/validate）。
`qt_resource_validate`	深挖 .qrc（naming / case-collision / depth / size / prefix）。

16. Git / 合规（4）

工具	用途
`qt_git_init`	初始化 git repo（Qt 专用 .gitignore）。
`qt_git_audit`	git 历史洞察（hot files / bus factor / churn / stale branches）。
`qt_release_notes`	自动生成 CHANGELOG.md 段（conventional-commits 分类）。
`qt_copyright`	license 头批量加（SPDX 检测）。

17. 游戏 / 状态 / UI 工具（12）

工具	用途
`qt_state`	QSettings 包装（APPDATA 持久化）。
`qt_save`	JSON save files（便携 + 易检查）。
`qt_score`	玩家排行榜（leaderboard）。
`qt_timer`	命名计时器（turn time / total game）。
`qt_replay`	步骤回放系统。
`qt_undo`	undo / redo 状态栈。
`qt_achievement`	游戏成就系统。
`qt_leaderboard_ui`	leaderboard widget（table 或 cards）。
`qt_anim`	QPropertyAnimation 代码生成（fade/move/scale/rotate/color/sequence）。
`qt_input`	键盘 / 鼠标 / 手柄 / focus chain / JSON 映射代码生成。
`qt_input_recorder`	鼠标键盘事件录制/回放（pyautogui）。
`qt_anim` (paintEvent 子类型)	double_buffer / painter_path / doodle_board（v0.3.8 教学性增强）。

18. 运行时 / IDE（7）

工具	用途
`qt_ui_action`	pywinauto 驱动运行中 Qt app（点击 / 输入 / 截图）。
`qt_widget_introspect`	snapshot/find/details 三合一 widget 树探查（0xCarbon 借鉴）。
`qt_runtime_props`	运行时 widget accessible properties 快照（借 0xCarbon qt_props）。
`qt_console_messages`	抓运行中 Qt app 的 QPlainTextEdit / QStatusBar 文本。
`qt_creator_open`	Qt Creator 直接打开 .pro（跳过欢迎页）。
`qt_creator_run`	Qt Creator 内 Ctrl+B + 启动 .exe。
`qt_designer`	designer.exe 打开 .ui 文件。
`qt_ide_metadata`	生成 .vscode/* + .idea/* 元数据（VSCode/CLion debug）。

19. 构建系统 / 包管理（5）

工具	用途
`qt_cmake`	生成 CMakeLists.txt（Qt5/Qt6 切换）。
`qt_conanfile_gen`	Conan recipes（conanfile.py + conanfile.txt + profiles）。
`qt_conda_env_gen`	conda-forge Qt 包（environment.yml + install 脚本）。
`qt_module_split_init` (CMake 版)	qt_module_split_cmake 同主题。
`qt_cmake_install`	见上文部署/分发段。

20. 杂项（5）

工具	用途
`qt_cheatsheet`	发现入口：打印 148 工具 quick reference（按 20 类别分组）。
`qt_moc_check`	单文件 moc 验证（不重编译）。
`qt_deps`	objdump 列 .exe DLL 依赖。
`qt_kill_exe`	终止 Qt 进程（taskkill /IM）。
`qt_smoke_test`	clean → build → run 三步健康检查。
`qt_log`	Qt log 按 level/category 过滤分析。
`qt_code_metrics`	项目健康报告（LOC / 注释率 / 函数复杂度等）。
`qt_heap_snapshot`	解析 Valgrind massif / heaptrack 输出。
`qt_asan_runtime_report`	把 ASan/UBSan/TSan 报告翻译成中文 + 修复建议。
`qt_modernize_qt5_to_qt6`	Qt 5 → Qt 6 自动迁移（6 条规则，dry_run 默认）。
`qt_modernize_qt6_string_literal`	`tr("中文")` → `tr(u"中文")` + u"" 前缀。
`qt_screenshot_diff` / `qt_screenshot_baseline_capture` / `qt_high_dpi_test`	视觉回归（pixel diff + baseline 捕获 + 多 DPI）。

总计：148 个工具（v0.4.4 + 1；v0.4.3 + 4；v0.4.2 + 4；v0.4.1 + 3；v0.3.8 + 7；v0.3.7 + 12；v0.3.6 + 5；v0.3.5 + 6；v0.3.4 + 5；v0.3.3 + 5；v0.3.2 + 5；v0.3.1 + 3；v0.3.0 + 4；v0.2.9 + 8；v0.2.8 + 6；v0.2.7 + 8；v0.2.6 + 5；v0.2.5 + 4；v0.2.4 + 5；v0.2.3 + 8；v0.2.0–v0.2.2 + 13）

决策指南：哪个工具做什么

你想做什么？	用这些工具
从零做 Qt 项目	`qt_scaffold --template=mainwindow` → `qt_build` → `qt_run`
自然语言描述 → 自动选模板	`qt_template_scaffold --description="..."`
加新类	`qt_class_wizard`
加 QML 组件	`qt_qml_component_gen --components=card`
完整暗色主题	`qt_palette_gen --mode=dark` → `qt_theme_gen --mode=dark` → 在 main.cpp 里 `applyPalette(*qApp); qApp->setStyleSheet(...)`
写测试	`qt_test`（C++）/ `qt_qml_test`（QML）/ `qt_test_fuzz`（fuzzing）
静态分析	`qt_lint` 一站式 / `qt_clazy_check` Qt 专属 / `qt_complexity_lint` 圈复杂度
CI 质量门	`qt_build` + `qt_test` + `qt_perf_budget` + `qt_format_check` + `qt_test_coverage_diff`
打包部署	`qt_deploy_bundle`（一站式）或 `qt_deploy` + `qt_signature` + `qt_installer_gen`
上 Steam	`qt_steamworks_init`
上 Microsoft Store	`qt_appx`
上 itch.io	`qt_itch_butler`
数据库持久化	`qt_db_seed` → `qt_db_validate` → `qt_db_dump`
MySQL 后端	`qt_mysql_setup`（重要：Qt 5.14 不带 QMYSQL 驱动）
HTTP API	`qt_http_client_gen --method=POST`
TCP 多人游戏	`qt_network --skeleton_type=tcp_server`
国际化	`qt_translate` → `qt_translation_validate` → `qt_translation_sync` → `qt_translation_auto_fill`（LLM 填）
修 signal/slot 反模式	`qt_signal_slot_trace` 诊断 → `qt_signal_lint_fix --apply` 修
doxygen 注释补全	`qt_documentation_lint` 找缺失 → `qt_documentation_auto_fill --apply` 补
Qt 5 → Qt 6 升级	`qt_modernize_qt5_to_qt6 --apply` + `qt_modernize_qt6_string_literal --apply`
跨平台依赖管理	`qt_conanfile_gen`（Conan）或 `qt_conda_env_gen`（conda-forge）
性能分析	`qt_perf_budget` + `qt_perf_compare` + `qt_heap_snapshot` + `qt_asan_runtime_report`
大项目拆分 lib/app	`qt_module_split_init`（qmake）或 `qt_module_split_cmake`（CMake）
打开 Qt Creator	`qt_creator_open`
在 VSCode/CLion 调试	`qt_ide_metadata`
找工具/查文档	`qt_cheatsheet` / `qt_docs_search`

完整工作流示例

示例 1：棋牌游戏全链路

1. qt_scaffold --template=chess_game --name=mygame
2. qt_theme_gen --mode=dark --output_file=mygame/dark.qss
3. qt_palette_gen --mode=dark --output_header=mygame/dark_palette.h
4. qt_qml_component_gen --components=card,board,tile
5. qt_assets --assets_dir=mygame/images/
6. qt_model_gen --class_name=CardModel
7. qt_viewmodel_gen --class_name=GameViewModel --properties=[...]
8. qt_state --action=save --key=score --data={...}    # 存档
9. qt_score --action=add --player=Alice --score=100    # 排行榜
10. qt_timer --action=start --timer_id=turn1
11. qt_input --action=keyboard --key_sequence=Esc --slot_name=onPause
12. qt_audio_convert --input_files=sfx/*.wav --output_format=mp3
13. qt_anim --animation_type=fade
14. qt_network --skeleton_type=tcp_server
15. qt_achievement --action=define --achievement_id=first_win
16. qt_undo --action=push --state_data={...}
17. qt_build
18. qt_test
19. qt_high_dpi_test --scale_factors=1.0,2.0
20. qt_screenshot_diff --image_a=baseline.png --image_b=current.png
21. qt_clazy_check --project_dir=mygame/
22. qt_translation_validate --ts_files=mygame/i18n/*.ts
23. qt_deploy_bundle --executable=mygame/release/mygame.exe
24. qt_signature_batch --action=sign --directory=mygame/deploy/

示例 2：Qt 5 → Qt 6 升级

1. qt_modernize_qt5_to_qt6 --project_dir=. --rule_ids=qregexp_to_qregularexpression
2. qt_modernize_qt6_string_literal --project_dir=. --apply
3. qt_build   # 验证编译通过
4. qt_test    # 验证测试通过

示例 3：CI 质量门（GitHub Actions）

- run: qt_smoke_test --project_dir=. --run_seconds=10
- run: qt_format_check --target=. --init_clang_format=true
- run: qt_perf_budget --executable=release/myapp.exe --budget_ms=2000
- run: qt_test_coverage_diff --baseline_info=coverage_old.info --current_info=coverage.info

环境变量

变量	默认值	作用
`QT_MCP_QT_ROOT`	`E:\Download_tools\QT\5.14.2\mingw73_64`	Qt 5.14.2 安装根目录
`QT_MCP_QT_32_ROOT`	`E:\Download_tools\QT\5.14.2\mingw73_32`	Qt 32-bit 安装目录
`QT_MCP_MINGW_BIN`	`E:\Download_tools\QT\Tools\mingw730_64\bin`	64-bit MinGW bin/
`QT_MCP_SANDBOX`	`E:\Download_tools\QT`	sandbox 根目录，所有 MCP 输入输出必须在此目录下
`QT_MCP_JSON`	（未设）	设为 `1` 时每个工具输出末尾追加 JSON footer（调试 / LLM 解析）
`QT_MCP_FFMPEG`	`E:\Download_tools\ffmpeg-8.1.1-essentials_build\bin\ffmpeg.exe`	ffmpeg 路径（`qt_audio_convert` 用）
`QT_MCP_DBGUI_EXE`	`C:/Program Files/SQLiteStudio/SQLiteStudio.exe`	SQLite GUI（`qt_db_open_in_gui` 用）
`QT_MCP_CPPCHECK_EXE`	`cppcheck`（PATH）	cppcheck 路径
`QT_MCP_QT_VERSION`	`5.14.2`	Qt 版本（写入元数据）

架构

Claude / MCP 客户端
       │ stdio JSON (一行 JSON 一个命令)
       ▼
  server.py (FastMCP)
       │
       ├─ 148 个 @mcp.tool 装饰的 async def qt_xxx(params) → str
       │
       ├─ 共享 helpers
       │   ├─ _json_footer()    # 每个工具结尾加 {ok, data}（QT_MCP_JSON 门控）
       │   ├─ _require_sandbox()  # 拦截 sandbox 外路径
       │   └─ _strip_comments()    # 静态分析前剥离注释
       │
       └─ subprocess 调 Qt SDK + 外部工具
              ├─ qmake / mingw32-make / windeployqt
              ├─ moc / uic / rcc / lupdate / lrelease
              ├─ qmllint / clang-format / cppcheck / ffmpeg
              ├─ objdump / signtool / git
              └─ pywinauto + UI Automation (运行时 widget 探查)

详细架构图见 docs/ARCHITECTURE.md。

跑测试

cd qt-mcp
unset QT_MCP_SANDBOX        # 让所有工具用默认 sandbox
python -m pytest -q         # 577+ passed in ~3min

或跑单个套件：

python -m pytest tests/full/e2e_new_tools_v32.py -v   # V0.4.4 新工具（10 tests）
python -m pytest tests/light/ -v                      # 快速 smoke（不需要 Qt SDK）

CI 在每次 push / PR 时自动跑（.github/workflows/ci.yml）：Windows runner + Python 3.12 + 全套测试。

项目结构

qt-mcp/
├── server.py              ⭐ 148 个工具全在这一个文件（约 30K 行）
├── pyproject.toml         pip install 配置
├── README.md              本文件
├── CHANGELOG.md           版本历史
├── PROJECT_FILES.md       文件结构详解
├── LICENSE                MIT 协议
│
├── docs/                  架构图 + 演示截图
├── examples/minimal/      5 分钟跑通的 hello Qt 示例
├── tests/                 577+ pytest（tests/full + tests/light）
├── .github/               issue / PR 模板 + GitHub Actions CI
└── docs_data/             Qt 文档 FTS5 索引（51 MB，由 build_docs_index.py 生成）

详见 PROJECT_FILES.md。

添加新工具

参考 qt_palette_gen（V0.4.4 新加）的流程：

在 server.py 合适位置插入 Pydantic Input + @mcp.tool 函数（约 200 行）
在 qt_cheatsheet catalog 加一行："qt_xxx": ("category", "description")
加 e2e 测试到 tests/full/e2e_new_tools_v<N+1>.py（至少 5 个测试：happy / edge / error）
更新 README.md 工具表 + 决策指南 + CHANGELOG.md 加 V0.X.Y 段
跑 pytest -q 验证 + 新套件 10/10 PASS
提醒用户重启 Claude Code（stdio MCP server 缓存工具列表，加完要重启才生效）

协议

MIT 协议。可随便用、商用、改源码、闭源分发。详见 LICENSE。

贡献

欢迎 PR。提交前请确认：

新功能有 Pydantic Input + 完整 docstring (Args/Returns/Raises/Note) + 至少 5 个 e2e 测试
现有测试全 PASS（577+）
更新 README.md + CHANGELOG.md
.github/PULL_REQUEST_TEMPLATE.md 检查清单全勾

仓库

GitHub: https://github.com/fan1959/qt-mcp
Issues: https://github.com/fan1959/qt-mcp/issues
当前版本: V0.4.4 (2026-09)

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
ChiR24-unreal_mcp_serverOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Developer Tools App Automation Software Architecture
2888
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748

Related MCP Servers

Qwen3 MCP Server
Coding Agents Developer Tools Autonomous Agents
marduk191
A
license
Not graded
quality
B
maintenance
A complete MCP server that gives LM Studio's Qwen3 (or any local LLM) full coding agent capabilities including 80+ tools for file operations, command execution, git, web search, memory, planning, and a full skills system.
Updated 8 months ago (2026-02-09 11:34 UTC)
13
MIT
ladder-mcp
Developer Tools Coding Agents
Arhimage
A
license
B
quality
C
maintenance
Windows-first MCP bridge for Kimi Code CLI, exposing code analysis, editing, sessions, and diagnostics as tools for AI agents.
Updated 3 months ago (2026-07-05 14:31 UTC)
6
21 npm
MIT
dev-mcp
CodeIbrah
A
license
Not graded
quality
B
maintenance
A local MCP server that gives AI agents access to developer tooling — GitHub (read-only), documentation search, and web research — via stdio transport.
Updated 2 months ago (2026-07-27 12:11 UTC)
MIT
qt-mcp
File Systems OS Automation
cristopulos
A
license
A
quality
C
maintenance
An MCP server for capturing screenshots of Qt/desktop windows and performing filesystem operations, enabling AI clients to inspect and modify project files.
Updated 2 months ago (2026-07-27 17:50 UTC)
15
MIT

qt-mcp

项目特点

V0.4.4 新增 1 个工具

5 分钟上手

前置条件

安装

配到 Claude Code

第一次使用

Qt 路径自定义

148 个工具完整清单

1. 脚手架 / 生成器（14）—— 从零创建 Qt 项目

2. 构建（6）

3. 运行 / 性能（4）

4. 测试（6）

5. 静态分析 / Lint（15）

6. 信号与槽 / QObject（6）

7. Q_PROPERTY / Runtime 反射（5）

8. 主题 / 样式（3）

9. 多媒体 / 资源（5）

10. 数据库（7）

11. 网络（3）

12. 文档 / i18n（7）

13. 部署 / 分发（9）

14. 环境 / SDK（6）

15. 文件 / 资源（6）

16. Git / 合规（4）

17. 游戏 / 状态 / UI 工具（12）

18. 运行时 / IDE（7）

19. 构建系统 / 包管理（5）

20. 杂项（5）

决策指南：哪个工具做什么

完整工作流示例

示例 1：棋牌游戏全链路

示例 2：Qt 5 → Qt 6 升级

示例 3：CI 质量门（GitHub Actions）

环境变量

架构

跑测试

项目结构

添加新工具

协议

贡献

仓库

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Qwen3 MCP Server

ladder-mcp

dev-mcp

qt-mcp