FreeCAD MCP execute_code 完全指南在 CAD 内部运行任意 Python 的 3 种姿势【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcpFreeCAD MCP是一个开源的 MCPModel Context Protocol服务器让你用 Claude Desktop 等 AI 客户端直接操控 FreeCAD创建模型、编辑几何、运行 Python 脚本、做 FEM 分析。其中execute_code是能力最强的一把钥匙——它把任意 Python 代码直接送进 FreeCAD 进程内部执行AI 从此不只是帮你点按钮而是真正在 CAD 内部编程。本文带你一次搞懂围绕execute_code的 3 种运行姿势GUI 线程同步执行、后台异步执行、无头进程执行。学完你就能让 AI 自动建模、批量改参数、安全地跑容易崩溃的 OCCT 重活。3 种 execute_code 姿势一张表看懂FreeCAD MCP 提供三个同族工具分别对应三种运行位置工具跑在哪里适合场景怎么拿结果execute_codeFreeCAD GUI 线程同步交互式建模、改属性、批量脚本执行完直接返回输出截图execute_code_async后台线程非 GUI长耗时几何计算布尔、放样返回job_id用get_async_status查询execute_code_headless独立freecadcmd进程容易崩溃的 OCCT 重活独立进程输出GUI 全程不受影响三者的取舍逻辑很简单普通自动化用execute_code计算太久会卡住 90 秒预算的用execute_code_async担心把整个 FreeCAD 拖崩的用execute_code_headless。官方文档把这个选择写得很直白见 docs/execution.md。姿势一execute_code —— 在 GUI 线程里同步跑任意 Pythonexecute_code是最常用的入口。它把代码派发到 FreeCAD 的GUI 线程上执行并同步等待结果。因为在 GUI 线程上所以文档操作addObject、recompute、save都是安全且顺序正确的——这正是大多数自动化脚本需要的环境。参数速查参数默认值说明code必填要执行的 Python 代码include_screenshottrue执行完自动回传一张模型截图AI 据此看见结果view_nameIsometric截图视角可选Front/Top/Right等 9 种timeout90 秒队列与执行预算各一份最大可提到 1800 秒使用前提在MCP Addon工作台点击工具栏的Start RPC Server状态栏出现 RPC Server started at 127.0.0.1:9875 即就绪。典型示例参数化生成一个法兰import FreeCAD doc FreeCAD.newDocument(Flange) base doc.addObject(Part::Cylinder, Base) base.Radius 45; base.Height 10 hub doc.addObject(Part::Cylinder, Hub) hub.Radius 12; hub.Height 30 flange doc.addObject(Part::MultiFuse, Flange) flange.Shapes [base, hub] doc.recompute()代码跑完工具会顺带回传一张等轴测截图——AI 看到图才知道模型长什么样这才敢继续下一步。纯计算脚本结果靠print把include_screenshot设为false可省不少 token。共享命名空间跨调用保留变量脚本像 REPLexecute_code与execute_code_async共享一个持久命名空间其中已注入FreeCAD/App和FreeCADGui/Gui别名。这意味着上一次调用定义的变量下一次调用直接可用非常适合分步建模式 AI 对话命名空间是独立 dict不会覆盖 RPC 服务自身函数避免意外冲突代码拥有 FreeCAD 的完整权限请谨慎execute_code_headless跑在独立新进程里不共享这个命名空间。源码里这个命名空间的定义很简洁rpc_server.py。姿势二execute_code_async —— 后台线程跑重活commit() 落回文档布尔运算、放样、扫掠这类 OCCT 计算动辄几十秒而execute_code的 GUI 线程预算默认只有 90 秒——超了就报超时任务其实还在跑但结果被丢弃。这时候换execute_code_async代码在后台线程运行并立刻返回job_id。铁律后台线程绝不能直接写文档或碰 GUIobj.Shape ...、doc.recompute()、addObject都不行。FreeCAD 文档和 Coin3D 场景图不是线程安全的从后台线程直接写会卡死事件循环RPC 彻底失联。正确姿势是用注入的commit()把落文档那一步交还给 GUI 线程fused base.fuse(addition).removeSplitter() # 慢活后台线程安全 def apply(): # 这行才跑在 GUI 线程 obj.Shape fused doc.recompute() commit(apply) # 交给 GUI 线程执行并等待拿到job_id后用get_async_status(job_id)查询running/done/failed状态失败时还能直接看到异常和 traceback。所有在跑的任务 最近 20 个已完成任务保留在内存中详见 docs/execution.md。推荐的三段式工作流用execute_code把 shape 取到模块级变量GUI 线程安全用execute_code_async跑重计算在commit()里应用结果或存成变量留给后续execute_code使用。姿势三execute_code_headless —— 独立进程执行崩溃也不怕有些 OCCT 操作makeHelixmakePipeShell的螺纹、复杂放样扫掠、大量 B 样条布尔可能直接段错误。如果发生在 GUI 进程里整个 FreeCAD 连同没保存的文档一起完蛋。execute_code_headless的解法是物理隔离把脚本写到文件在独立的freecadcmd进程里执行。原生崩溃如SIGSEGV只会结束辅助进程工具会把崩溃信号和脚本的全部打印输出报给你GUI 和已打开文档安然无恙默认超时 600 秒必须为正有限值超时返回部分 stdout/stderr临时脚本成功/失败/超时都会清理可执行文件自动检测PATH 上的freecadcmd或 Snap 的freecad.cmd、Flatpak 的org.freecad.FreeCAD也可用--freecadcmd参数覆盖逻辑见 headless.py。注意headless 脚本跑在MCP 服务器所在机器上与--host指向的 GUI 无关文件路径要用服务器机器上可访问的。它也不共享 GUI 命名空间需要自己导入模块、自己开档存档import FreeCAD doc FreeCAD.openDocument(/path/to/part.FCStd) # ... 重活 ... doc.save() # 或 shape.exportBrep(/path/out.brep)脚本保存了 GUI 中已打开的.FCStd后调用reload_document(doc_name)刷新 GUI 里的副本即可看到结果。超时、卡住与排错GUI 线程的两笔预算execute_code有两笔独立预算队列预算等待前面任务执行完和执行预算真正在 GUI 线程上跑的时间默认各 90 秒。传一个正的有限timeout上限 1800 秒可以同时放宽两者客户端会相应放宽 socket 超时。导入/导出大型 STEP 装配这类必须在 GUI 线程、就是慢的活就提高timeout纯几何重活优先改用execute_code_asyncGUI 任务一旦开始无法取消超时的execute_code会报超时但任务继续在后台跑完结果被丢弃若某个 GUI 操作卡死桥接会返回GUI_DISPATCH_STUCK并拒绝后续 GUI 操作。用另一个 RPC 客户端调get_rpc_status定位是哪个操作还在跑状态恢复不了就重启 FreeCAD。完整规则见 docs/execution.md。总结3 种姿势怎么选你的情况选择常规建模、改属性、批量脚本execute_code安全默认长耗时几何计算怕超过 90 秒预算execute_code_asynccommit()可能崩溃的 OCCT 重活螺纹/放样/复杂布尔execute_code_headless只想看当前画面get_view查任务状态 / 诊断卡死get_async_status/get_rpc_status掌握这 3 种姿势AI 在你手里的 FreeCAD 里就从能用变成好用日常建模走 GUI 线程重活丢给后台危险操作扔进独立进程——稳、快、不翻车。延伸阅读代码执行完整文档docs/execution.md全部工具清单与截图选项docs/tools.md工具服务端定义server.py操作层实现operations/core.py安装指南docs/installation.md配置说明自动启动、文本反馈、远程连接docs/configuration.md【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考