qcad-mcp

QCAD MCP

**AI 驱动的 2D CAD 自动化——DXF/DWG 解析、3D 拉伸、持久化文件库、房间分析和完整的增删改查管理。**提供 12 个用于 DXF 处理的 MCP 工具（8 个组合工具 + 4 张 Prefab 卡片）。让你的 AI 助手成为 QCAD Pro 操作员。

适用场景……	希望让 AI 以编程方式处理平面图、将 DXF 转换为适用于 Resonite/Unity3D 的 3D 模型、维护持久化 CAD 文件库，或自动化制图工作流。
连接对象	ezdxf（免费的 Python 引擎），用于所有解析、渲染、拉伸和分析
端口	后端 11966，仪表板 11967
启动	先运行 just bootstrap，然后运行 start.ps1

MCP 工具

v0.5.0 组合工具接口：每个工具都接受一个 op 判别参数以及该操作的参数（旧的按操作划分的名称仅作为 Web 应用内部别名保留）。

工具	访问权限	用途
plan	读取/修改	核心 ezdxf 操作：info、to_svg、extrude、stack、obj、glb、drawings、export、analyse、create、depot
plan_edit	修改	convert（通过 QCAD Pro 转换 DWG↔DXF）、modify（图层/实体）
plan_annotate	读取/修改	dimension、measure、text、hatch、block_insert、array、wall_data、beam_analysis
plan_pro	修改	QCAD Pro：script、render、exec（ECMAScript）
plan_library	读取/修改	blocks、blocks_download、scripts_search、scripts_download
plan_ai	修改	generate（自然语言平面图）、agentic（自然语言工作流）、transpile（AutoLISP）、sampling（由宿主大模型进行推理）
plan_bim	读取/修改	auto_dimension、building_meta、to_ifc_data（BIM 交接）
qcad	读取	status（QCAD Pro 安装状态）、help（实时目录）、shutdown（有序退出）
show_qcad_status_card	读取	Prefab 卡片：QCAD Pro 状态
show_depot_card	读取	Prefab 卡片：文件库文件
show_beam_analysis_card	读取	Prefab 卡片：梁的 FEA 结果
show_building_meta_card	读取	Prefab 卡片：建筑元数据

Fleet 交叉连接（配套服务）

qcad-mcp 完全可以独立运行。你也可以选择将它连接到 sandraschi Fleet 中的配套服务，以启用扩展功能：

配套服务	可启用的功能	状态	设置
blender-mcp	3D 场景拉伸、渲染 DXF 布局	可选	安装指南
freecad-mcp	将 2D 草图转换为参数化 3D 模型	可选	安装指南

自包含的配套服务：Fleet 配套服务可独立运行。安装配套服务不会触发传递依赖链。

CAD 仓库（持久文件存储）

所有 CAD 文件都存储在持久仓库 %LOCALAPPDATA%\qcad-mcp\depot 中，服务器重启或系统重新启动后仍会保留。可通过环境变量 QCAD_MCP_DEPOT 配置。

通过 REST API 管理仓库（CRUD）：

端点	方法	说明
/api/v1/depot	GET	列出所有文件及其元数据（大小、日期、说明、标签）
/api/v1/depot/{name}	GET	下载 DXF 文件
/api/v1/depot/{name}	PUT	重命名或更新说明/标签
/api/v1/depot/{name}	DELETE	删除文件及元数据附属文件
/api/v1/depot/create	POST	根据 JSON 实体规格创建 DXF（直线、矩形、圆、文本、折线）
/api/v1/depot/upload	POST	将 DXF/DWG 直接上传到仓库

REST API

端点	方法	说明
/api/v1/status	GET	服务器运行状况、ezdxf 版本、QCAD Pro 状态
/api/v1/upload	POST	上传 DXF/DWG（也会保存到仓库）
/api/v1/download/{name}	GET	下载 SVG/STL/PDF/PNG 输出文件
/api/v1/files	GET	列出所有文件（仓库 + 输出文件）
/api/v1/depot/*	GET/PUT/DELETE	对持久 CAD 仓库执行完整的 CRUD 操作
/api/v1/control/tool	POST	执行任意 MCP 工具
/api/v1/logs/stream	GET	SSE 实时日志流
/api/v1/chat	POST	通过 Ollama 与 CAD 专家聊天
/api/v1/settings	GET/PUT	大模型 + 拉伸默认值 + QCAD Pro 路径

Web 应用页面

路由	页面	说明
/	仪表板	主视觉横幅、QCAD Pro 状态面板、仓库统计信息、ezdxf 版本
/demo	AI CAD 演示	自然语言 → 平面图 → SVG → 3D STL。预设卡片、流水线步骤指示器、选项卡式结果
/chat	聊天	流式大模型聊天、技能优先、6 种个性、历史记录、导出
/inbox	收件箱	新文件审核队列，支持内嵌预览和 Viewer 链接
/tools	工具	Portmanteau 工具目录，含操作标签和 Playground 深层链接
/skills	技能	技能浏览器（与 Chat 用作系统提示词的文件相同）
/depot	仓库	完整的 CRUD 文件浏览器，支持 SVG 预览、创建 DXF 向导、上传、重命名和删除
/viewer	查看器	上传 DXF + SVG 预览，支持按图层切换
/extrude	拉伸	DXF → STL，支持控制墙高、墙厚和墙图层
/analyse	分析	房间检测、面积表、门窗列表
/layers	图层	图层可见性、冻结/锁定、重命名、批量操作
/blocks	图块	从库中搜索 4800 多个 CAD 图块并下载
/scripts	脚本	浏览 QCAD ECMAScript 脚本库 + 保存本地脚本
/agentic	AI Agent	自主多步骤 CAD 工作流（QCAD Pro）
/batch	批处理	对所有仓库文件运行信息查询/分析/拉伸。支持 STL 批量拉伸并提供图库
/pipeline	流水线	5 步向导：描述 → SVG → 分析 → STL → 导出 FreeCAD 墙体数据
/playground	Playground	工具 API 测试器：选择任意工具、编辑 JSON 参数、执行并查看原始响应
/models	模型	上传文件与输出文件列表，支持下载
/logs	日志	实时 SSE 日志查看器，支持筛选/导出/暂停
/settings	设置	大模型提供商/模型、拉伸默认值、QCAD Pro 路径
/help	帮助	10 个选项卡的参考资料：QCAD、ezdxf、工具、流水线、格式、集群
docs/floorplan-sources.md	—	免费、付费及历史平面图来源 + 栅格图→DXF 流水线

快速开始

just bootstrap   # uv sync + bun install
start.ps1        # kills zombies, starts backend + frontend, opens browser

安装（Claude Desktop，Windows）

irm https://github.com/sandraschi/qcad-mcp/releases/latest/download/install.ps1 | iex

将稳定版 qcad-mcp.mcpb 捆绑包安装到 Claude Desktop。其他 客户端（Cursor、VS Code、OpenCode）：使用 uvx 和 stdio 入口：

{
  "mcpServers": {
    "qcad-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "D:\\Dev\\repos\\qcad-mcp", "run_server.py"]
    }
  }
}

MCP 客户端配置

{
  "mcpServers": {
    "qcad": {
      "url": "http://localhost:11966/sse",
      "transport": "sse"
    }
  }
}

栅格图像 → DXF 流程（计划中）

将平面图印刷件扫描为可用的 DXF 很简单：

Book/magazine page → scanner (300-600 DPI)          inkscape-mcp
                         ↓                          (Trace Bitmap)
                    Potrace / Inkscape                    ↓
                         ↓                          QCAD MCP
                    Raw vector DXF                    (plan_edit(op="modify"))
                         ↓
                    Clean up in QCAD / plan_edit(op="modify")

步骤	工具	作用
扫描	任意扫描仪	300-600 DPI，灰度或黑白，保存为 PNG/TIFF
矢量化	inkscape-mcp trace_bitmap() 或 potrace CLI	将栅格线条转换为 SVG 路径
转换	SVG → DXF（通过 potrace 或 ezdxf）	可在任意 CAD 程序中打开
清理	qcad-mcp plan_edit(op="modify")	合并短线段、删除杂散标记、重新分配图层、重新标注尺寸

有两种方法：

1. inkscape-mcp 方案——将扫描后的 PNG 发送给 inkscape-mcp 的 trace_bitmap() 工具，获取带有规范路径几何的 SVG。该 SVG 可顺利导入 QCAD，成为可操作的实体。
2. qcad-mcp 中的 potrace——添加一个 plan_raster_to_dxf(file_name) 工具，用 potrace + ezdxf 封装实现。完整自包含，无需外部服务。

无论采用哪种方法，结果都要通过 plan_edit(op="modify") 进行清理（删除噪点、合并墙体线段、重新分配图层、重新添加尺寸标注）。Demo 页面中的巴洛克教堂预设证明了参数化几何可行——扫描功能将让你能够采集真实的现有建筑。

QCAD Pro 定价——€50？真的？

QCAD Professional 的单用户许可证售价为 €50.40——永久有效，无订阅费用。与每年 2,000 多美元的 AutoCAD 相比，这个价格看起来低得离谱，但 RibbonSoft 的收入模式更为精细：

产品	价格	市场
Community Edition	免费（GPLv3）	爱好者、学生、创客
QCAD Professional	€50.40	独立专业人士、小型公司
QCAD Pro Site License	€440.40	公司（不限席位，单一地点）
QCAD Pro Server License	€583.20	可自托管部署
QCAD Pro Scalable Server	€1,771.20	企业级规模
QCAD/CAM（CNC 插件）	€132.00	制造业
QCAD/CAM Site License	€1,173.60	CNC 加工厂
Books / E-Books	每本 €40–42	文档，被动收入

其策略是开放核心的免费增值模式，通过企业站点许可证获利：

1. Community Edition 确实免费且功能强大（GPLv3）。它是巨大的用户漏斗——建筑师、创客和学生用它学习、推荐它，最终他们的雇主会购买站点许可证。
2. €50 个人版采用无门槛的“冲动购买”定价——不需要 PO 审批，也不用与供应商谈判，直接购买即可。
3. **站点和服务器许可证（€440–€1,771）**才是真正的收入来源。一家拥有 20 个席位、支付 €440 的建筑公司，胜过 200 个各付 €50 的个人用户。SaaS/本地部署的服务器许可证还可以进一步扩展收入。
4. QCAD/CAM 售价 €132，覆盖 CNC/制造业细分市场——这是一个独立且价值更高的市场。
5. 售价 €40 的图书纯属利润——手册已经写好，印刷成本可以忽略不计。

RibbonSoft 是一家位于萨尔嫩的瑞士有限责任公司（GmbH），并非退休人士经营。他们办公室 100% 的能源来自瑞士水电（他们非常自豪，甚至把这点写在页脚里）。自 1999 年起，他们一直采用可持续的自力创业模式，至今已有 26 年多。

**谁会付费？**班加罗尔的 Ganesh 用 Community Edition 处理住宅项目——它能完美处理印度建筑规范图纸所需的 DXF。当客户要求导出 DWG 或 PDF 时，他就花 €50 升级到 Pro——一个项目就能回本。随着业务扩展到超过 5 个席位，他会升级为站点许可证。与此同时，一家欧洲建筑公司为了合规支付 €440，毫不犹豫。只有在有人代付时，湾区的 Autodesk 税（每年 2,500 多美元）才说得过去。

€50 在任何地方都能轻松跨过购买门槛。不需要 PO 审批，不用与供应商谈判，也没有订阅倒计时。买一次，就永久拥有。

质量保障

• Python：Ruff 代码检查 + 格式化，Pyright 类型检查（0 个错误）——src/ + run_server.py
• 前端：Biome + tsc --noEmit + bun 锁文件——22 个 TypeScript 页面
• 协议：FastMCP 3.4（stdio + HTTP /mcp）+ 40 个 REST 路由
• 工具：12 个 MCP 工具（8 个组合工具 + 4 张 Prefab 卡片），带有 READ_ONLY/MUTATING 注释
• 自动化：用于所有集群操作的 Justfile 配方
• 测试：pytest（78+）+ Playwright 端到端测试规范

许可证

MIT — 详见 LICENSE。