Skip to main content
Glama
fan1959

qt-mcp

by fan1959
OverviewSchemaRelated ServersScoreDiscussions
Python

qt-mcp

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

项目简介

qt-mcp 把 Qt SDK 工具链（qmake / mingw32-make / windeployqt / moc / lupdate / qmllint / clang-format 等）变成可调用的 MCP 工具——Claude 调一个 qt_build 就等于替用户在终端跑 qmake + make。工具覆盖 Qt C++ 项目完整生命周期，从空目录到带签名的安装包。

  • 协议：MIT

  • 依赖：Python ≥ 3.10

  • 平台：Windows（依赖 pywinauto + Qt 5.14.2 MinGW）

  • 实现：单文件 server.py（29,795 行 Python，147 个工具，零 C++ 源码污染）

  • 测试：561 个 pytest（全过），分 light / full 两套

核心特点

  • 完整覆盖 Qt 项目生命周期：脚手架、构建、运行、测试、格式化、部署、签名、安装包一条龙

  • 本地 FTS5 全文检索：Qt 5.14.2 自带 6613 页文档建成索引（51 MB），100 ms 内搜到答案

  • AI 友好的诊断信息：qt_build 把编译器 / moc / uic / 链接器输出解析成结构化 JSON，并给出可执行的修复建议

  • 路径沙箱保护：所有工具强制路径必须在 sandbox 根下，跨边界访问直接拒绝（Error: ...）

  • 零样例代码污染：所有 Qt 二进制（*.exe / *.dll）走 subprocess 调真实 Qt SDK，仓库内不引入任何 C++ 源码

  • 单文件 server.py：147 个工具全部在一个文件里（约 3 万行），跨工具共享 helpers 不重复

5 分钟上手

前置条件

  • Windows 10 / Windows 11

  • Qt 5.14.2 已装（默认路径 E:\Download_tools\QT\5.14.2\mingw73_64）

  • MinGW 730_64 已装

  • Python ≥ 3.10

安装

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

工具一览（147 个，按 19 个分类）

所有工具都是 Python async def，签名见 server.py。

分类

数量

工具

项目脚手架

13

qt_scaffold / qt_template_scaffold / qt_class_wizard / qt_pro_edit / qt_pro_lint / qt_pro_project_graph / qt_module_split_init / qt_module_split_cmake / qt_qobject_invoke_property_diff / qt_gen_qrc / qt_assets / qt_resources / qt_resource_validate

构建

5

qt_build / qt_clean / qt_shadow_build_setup / qt_build_cache / qt_build_diagnostics

运行

8

qt_run / qt_run_trace / qt_kill_exe / qt_perf_budget / qt_perf_compare / qt_smoke_test / qt_dll_search_path / qt_diagnose_env

测试

5

qt_test / qt_qml_test / qt_test_fuzz / qt_sanitizer_run / qt_test_coverage_diff

静态分析

12

qt_clazy_check / qt_cppcheck / qt_complexity_lint / qt_lint / qt_format_check / qt_format / qt_analyze / qt_async_await_lint / qt_thread_affinity_check / qt_signal_slot_trace / qt_signal_disconnect_check / qt_signal_lint_fix

文档与搜索

5

qt_docs_search / qt_docs_gen / qt_documentation_lint / qt_documentation_auto_fill / qt_translate

部署与签名

8

qt_deploy / qt_deploy_bundle / qt_signature / qt_signature_batch / qt_installer_gen / qt_appx / qt_ico_create / qt_svg_to_png

数据库

6

qt_db_seed / qt_db_validate / qt_db_dump / qt_db_open_in_gui / qt_db_schema_diff / qt_db_perf_index

网络

4

qt_network / qt_http_client_gen / qt_ftp_client_gen / qt_asan_runtime_report

多媒体

2

qt_multimedia_setup / qt_audio_convert

QML

5

qt_qml_lint / qt_qml_perf_lint / qt_qml_component_gen / qt_qmlscene / qt_qml_property_linter

Qt 3D

1

qt_qtquick_3d_setup

C++ 重构

3

qt_modernize_qt5_to_qt6 / qt_modernize_qt6_string_literal / qt_input_recorder

信号与槽 / QObject

8

qt_qobject_invocation_count / qt_qobject_invocation_history / qt_qobject_invoke_metadata / qt_qobject_invoke_connect_monitor / qt_qproperty_browser / qt_hotreload_check / qt_property_browser / qt_widget_introspect

教学与示例

4

qt_cpp_tutorial_scaffold / qt_graphics_view_scaffold / qt_input / qt_anim

主题与样式

4

qt_theme_gen / qt_qstyle_sheet_gen / qt_qss_inspect / qt_layout_check

游戏 / 棋牌

1

qt_scaffold --template chess_game / tictactoe_game / breakout_game / cards_game / music_player / tasklist / gomoku / gobang

其他实用

8

qt_achievement / qt_leaderboard_ui / qt_replay / qt_save / qt_state / qt_score / qt_timer / qt_translation_sync

运行时 UI 自动化

5

qt_ui_action / qt_widget_introspect / qt_runtime_props / qt_console_messages / qt_creator_open / qt_creator_run / qt_designer

完整列表见 PROJECT_FILES.md。

典型工作流

1. 从空目录到可运行 .exe

你 → qt_scaffold(template=mainwindow, output_dir=F:/demo/hi)
    → qt_build(project_dir=F:/demo/hi)
    → qt_run(executable=F:/demo/hi/debug/hi.exe, detach=True)
    → qt_ui_action(action=screenshot, output_path=hi.png)

2. 加新类 + 改 .pro

你 → qt_class_wizard(class_name=Counter, output_dir=F:/demo/hi)
    → qt_pro_edit(action=append, variable=SOURCES, values=Counter.cpp)
    → qt_build(project_dir=F:/demo/hi)

3. 调试编译错误

你 → qt_build(project_dir=F:/demo/hi)              # 失败
    → qt_build_diagnostics(project_dir=F:/demo/hi)  # 结构化诊断：file:line + 建议
    → qt_grep(project_dir=F:/demo/hi, pattern=QPushButton)  # 验证符号存在
    → qt_class_wizard(... type=QPushButton ...)     # 一键生成

4. 部署 + 签名 + 安装包

你 → qt_deploy(executable=F:/demo/hi/release/hi.exe)
    → qt_signature_batch(directory=F:/demo/hi/release, action=sign, certificate_path=cert.pfx)
    → qt_installer_gen(output_dir=F:/demo/hi/installer, exe_path=hi.exe, app_name=hi)
    → 运行 build_installer.bat 生成 .msi

环境变量

变量

默认值

作用

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 安装目录（跑 32-bit .exe 时用）

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（调试用）

架构

Claude / MCP 客户端
       │ stdio JSON (一行 JSON 一个命令)
       ▼
  server.py (FastMCP)
       │
       ├─ 147 个 @mcp.tool 装饰的 async def qt_xxx(params) → str
       │
       ├─ 共享 helpers
       │   ├─ _json_footer()       # 每个工具结尾加 {ok, data}
       │   ├─ _require_sandbox()   # 拦截 sandbox 外路径
       │   ├─ _strip_comments()    # 静态分析前剥离注释
       │   ├─ _qt_env()            # 拼装 Qt + MinGW 子进程环境
       │   ├─ _pro_parse()         # .pro 文件解析（生成 AST dict）
       │   └─ _run()               # 统一 subprocess 管道
       │
       └─ subprocess 调 Qt SDK 二进制
              ├─ qmake / mingw32-make
              ├─ windeployqt
              ├─ moc / uic / rcc
              ├─ lupdate / lrelease
              ├─ qmllint / qmlscene
              └─ clang-format / cppcheck

server.py 内部分区（按职责）

区段

行号

内容

imports + 常量

1-100

stdlib + mcp + pydantic + 模板导入

Qt 环境 + sandbox

100-150

_env_path() / _require_sandbox() / _pe_bits()

subprocess 管道

150-200

_qt_env() / _run() / _clean_artifacts() / _json_footer()

.pro 解析器

200-280

_pro_strip_comments() / _pro_parse() / _pro_serialize()

模板 / 数据类

280-800

ScaffoldTemplate enum + 9 个模板的 _*_file() 发射器

Pydantic Input 模型

800-17000

每个工具一个 QtXxxInput(BaseModel)

工具实现

17000-29795

所有 @mcp.tool 函数

入口

末 5 行

if __name__ == "__main__": sys.exit(main())

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

内部机制

路径沙箱（_require_sandbox）

每个工具接受的路径参数都过一遍 _require_sandbox(path, what)：

  1. path.resolve() 求绝对路径

  2. 若解析后不在 QT_MCP_SANDBOX 根下 → 返回 Error: ... outside sandbox

  3. 工具短路返回

这意味着你不能在 sandbox 外对文件做操作。覆盖范围：

set QT_MCP_SANDBOX=D:/my_projects   # 限制只在这棵树下

错误处理哲学

  • 每个工具返回字符串（不是类型化响应）——保持 MCP 协议简单，输出可 pipe 给 tee / grep

  • 错误一律以 Error: 开头——单次 grep 即可找全

  • qt_build 失败后追加 --- diagnostics (JSON) --- 块，含 file/line/column/tool/code/message/suggestion

  • _json_footer(obj) + QT_MCP_JSON=1 提供统一的 --- json ---\n{ok,data|error} 段（机器可读）

关键 helpers

Helper

作用

_json_footer(obj)

给每个工具输出末尾追加 --- json ---\n{ok, ...} 段

_require_sandbox(path, what)

强制路径必须在 QT_MCP_SANDBOX 内

_strip_comments(text)

静态分析前剥离 C++ / QML 注释（避免 if (s == "if") 被误算）

_qt_env()

拼装 Qt + MinGW 子进程环境（PATH 注入 Qt bin / MinGW bin）

_pro_parse(pro_file)

解析 .pro 文件返回 AST dict（变量 + 值列表），_pro_serialize() 反向

_pe_bits(exe_path)

PE-header heuristic 判 32 / 64-bit，选对应 Qt bin

_run(cmd, cwd, timeout)

统一 subprocess 管道，捕获 stdout/stderr/returncode

_docs_index_dir()

懒加载 FTS5 索引（首次调 qt_docs_search 时构建）

跑测试

cd qt-mcp
unset QT_MCP_SANDBOX        # 让所有工具用默认 sandbox
python -m pytest -q         # 全套测试

或跑单个套件：

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

测试组织

目录

数量

何时跑

tests/light/

6 个套件 / <5s

不需要 Qt SDK，跑纯 Python 逻辑（解析器 / helpers / 沙箱拒绝）

tests/full/

555 个套件 / ~155s

需要 Qt 5.14.2 + MinGW，跑真实 qmake + make

每加一个新 sprint，就加一个 tests/full/e2e_new_tools_v<N>.py，至少 5 个 e2e 测试 + 完整 happy path / error path。

测试隔离模式

新工具的 e2e 测试统一用：

@pytest.fixture(autouse=True)
def _qt_mcp_json(monkeypatch):
    monkeypatch.setenv("QT_MCP_JSON", "1")

让每个工具输出末尾有稳定 JSON footer。_split_json() helper 宽容解析不崩。

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

项目结构

qt-mcp/
├── server.py              ⭐ 147 个工具全在这一个文件（29,795 行）
├── pyproject.toml         pip install 配置
├── README.md              本文件
├── CHANGELOG.md           版本历史
├── PROJECT_FILES.md       文件结构详解
├── LICENSE                MIT 协议
│
├── docs/                  架构图 + 演示截图
│   ├── ARCHITECTURE.md
│   └── demo/              qt-mcp 6 步走查
├── examples/minimal/      hello Qt 5 分钟示例 + .mcp.json
├── tests/
│   ├── light/            6 个无 Qt SDK 套件
│   └── full/             555 个 e2e 套件（每加一工具配一个 e2e_new_tools_v<N>.py）
├── .github/               issue / PR 模板 + GitHub Actions CI
└── docs_data/             Qt 6613 页文档 FTS5 索引（51 MB，build_docs_index.py 生成）

详见 PROJECT_FILES.md。

FAQ

Q: stdio server 加了新工具，Claude 不认怎么办？ A: 重启 Claude Code。stdio MCP server 在启动时缓存工具列表，加完必须重启会话生效。

Q: windeployqt 漏拷 Qt5Sql.dll / sqldrivers/ 怎么办？ A: 在 main.cpp 加一行 qDebug() << QSqlDatabase::drivers(); 强制链接 Qt5Sql。qt_deploy 会自动检测。

Q: 32-bit / 64-bit 不匹配导致 .exe 一启动就崩？ A: 跑 qt_diagnose_env(deep=True) 检查 PATH 顺序 + Qt bin bitness。qt_dll_search_path 分析缺失的 DLL。

Q: MCP 客户端连不上 qt-mcp？ A: 检查 ~/.claude.json 里的 mcpServers.qt-mcp.command + args，手动跑 python -m server 看 stderr。

Q: 怎么给项目定制 Qt 路径？ A: set QT_MCP_QT_ROOT=D:/Qt/5.14.2/mingw73_64，重启 Claude Code。

Q: 我的项目不在 sandbox 根下？ A: set QT_MCP_SANDBOX=D:/my_projects，所有工具自动限制在这棵树下。

Q: e2e_v.py 测试有 QT_MCP_JSON 依赖怎么隔离？ A: 套件顶部加 pytest.fixture(autouse=True) 设 QT_MCP_JSON=1，用 _split_json() helper 解析。

协议

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

仓库

This server cannot be installed

-
license - not tested
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fan1959/qt-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server