FreeCAD MCP 三种执行模式怎么选execute_code / async / headless 终极对比【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcpFreeCAD MCP 是一个让 Claude Desktop 等 AI 助手直接操控 FreeCAD 的 MCPModel Context Protocol服务器可以建模、跑 Python 脚本、查看文档、执行 FEM 分析。它的代码执行能力分为三种模式execute_code、execute_code_async异步和execute_code_headless无头模式。本文帮你在 1 分钟内搞清楚三者的区别并给出直接的选择建议。30 秒快速决策选哪个执行模式模式运行位置适合的任务时间预算execute_codeFreeCAD GUI 主线程常规建模、编辑对象、截图反馈默认 90 秒可调到 1800 秒execute_code_async后台工作线程长时间、独立的几何计算返回job_id轮询状态execute_code_headless独立的freecadcmd进程可能让 OCCT 崩溃的重载操作默认 600 秒一句话决策常规操作选execute_code跑几分钟且只算几何、不碰界面选 async怕把 FreeCAD 搞崩的危险任务选 headless。共同前提先启动 RPC 服务器三种模式都跑在已连接的 FreeCAD 之上。安装好附加组件并重启 FreeCAD 后从工作台列表选择MCP Addon再在FreeCAD MCP工具栏点击Start RPC Server状态栏显示监听地址默认127.0.0.1:9875即启动成功详细步骤见 安装指南。模式一execute_code —— 默认首选直接跑在 GUI 线程execute_code是最常用的执行模式脚本直接在 FreeCAD 的 GUI 线程上运行因此它可以直接读写文档、操作视图并返回截图是普通建模任务的默认选择。适用场景️创建/修改/删除对象、导入导出模型需要即时看到效果的交互式建模如演示图中的法兰运行 FEM 悬臂梁示例 这类标准脚本关键机制共享脚本状态execute_code与 async 共享一个持久脚本命名空间内置FreeCAD/FreeCADGui别名变量在多次调用之间保留无需每次重新定义超时预算队列等待与执行各有 90 秒预算耗时更久的 GUI 任务可传入timeout正数、上限 1800 秒客户端会自动放宽套接字超时卡死恢复GUI 任务一旦开始就无法取消。若任务超时卡住桥接层返回GUI_DISPATCH_STUCK可另开一个客户端用get_rpc_status诊断仍不恢复则重启 FreeCAD完整规则见 代码执行文档。模式二execute_code_async —— 长耗时后台计算与任务跟踪当几何计算要跑几分钟又不想阻塞 GUI 时用execute_code_async。它把脚本丢到独立的工作线程立即返回一个job_id用get_async_status(job_id)查询任务是running、done还是failed失败时附带异常和堆栈不带参数可查看全部任务历史工作线程里构建独立的 OCCT 几何再用commit(fn, timeout120)回到 GUI 线程应用结果并重算文档与execute_code共享持久脚本命名空间之前定义的变量可以直接复用适用场景⚡只涉及几何、不碰文档和视图的纯计算扫描、放样、批量布尔可以提交后先去干别的的批处理型建模像下面这类带复杂轮廓的零件建模过程往往就是典型的长耗时几何任务模式三execute_code_headless —— 崩溃隔离的独立进程执行execute_code_headless是保险箱模式脚本被写入临时文件用freecadcmd -c在单独的进程中执行。螺旋扫掠makeHelixmakePipeShell、复杂放样、带大量 B 样条的布尔运算这类操作可能让 OpenCascade 段错误——在 GUI 进程里跑会连同所有未保存文档一起崩溃而在无头进程里崩溃只会结束辅助进程工具会报告信号如SIGSEGV和脚本全部输出GUI 安然无恙。使用注意️脚本要自己管理文档自行FreeCAD.openDocument创建、doc.save()或Shape.exportBrep导出保存了 GUI 中打开的.FCStd后用reload_document刷新界面副本可执行文件在MCP 服务器所在机器上运行文件路径必须是该机器可访问的--host参数只影响 GUI RPC 连接freecadcmd自动检测PATH 或 Flatpak也可用--freecadcmd参数显式指定实现逻辑可参考 headless 执行器源码工具注册见 MCP 服务器源码。常见坑位 FAQ问async 脚本里能直接改文档吗不能。文档和视图访问必须留在 GUI 线程用commit()把最终函数提交过去。问execute_code 超时了怎么办任务无法取消结果会被丢弃但计算仍在跑。耗时任务请显式传timeout纯几何计算请改用execute_code_async。问headless 结果和 GUI 里的文档不一致无头脚本运行在新进程中不与 GUI 共享脚本状态和文档保存后用reload_document同步即可。问脚本变量在多次调用之间丢了吗execute_code和 async 共享持久命名空间变量会保留headless 每次都是全新进程不会保留。相关文档与资源执行模式完整说明docs/execution.md全部工具一览docs/tools.md安装与连接docs/installation.md演示与示例docs/examples.md附加组件GUI 侧 RPC 服务器addon/FreeCADMCP/服务器端操作实现src/freecad_mcp/operations/core.py【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考