FreeCAD MCP 全解：16 个核心工具清单，一张表看懂 AI 如何驱动 FreeCAD
【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp
FreeCAD MCP 是一款开源的 MCP（Model Context Protocol）服务器，让 Claude Desktop 等 AI 客户端能够"驾驶"三维建模软件 FreeCAD：创建文档与零件、编辑属性、执行 Python 脚本、查看视图截图，甚至运行 FEM 结构分析，全部通过一句自然语言完成。本文用一张表盘点它的 16 个核心工具，讲清三种代码执行模式与快速上手步骤，帮助新手快速理解 AI 驱动 FreeCAD 的完整链路。
一、FreeCAD MCP 是什么？两个组件 + 一条通信通道
🧩 整个系统由两部分组成，各司其职：
| 组件 | 位置 | 职责 |
|---|---|---|
| FreeCAD 端插件（Addon） | addon/FreeCADMCP/ | 运行在 FreeCAD 内部，提供工作台与 RPC Server（默认监听127.0.0.1:9875） |
| 外部 MCP Server | src/freecad_mcp/ | 由 AI 客户端通过uvx freecad-mcp启动，把 AI 的工具调用翻译成对 FreeCAD 的 RPC 请求 |
通信流程很简单：AI 客户端 → MCP Server → XML-RPC → FreeCAD 插件 → 3D 模型。AI 说"帮我建一个圆角法兰"，FreeCAD 里就会真的长出一个零件。
安装插件后重启 FreeCAD，即可在工作台列表底部看到MCP Addon选项：
选中该工作台并点击工具栏上的Start RPC Server，FreeCAD 状态栏会显示"RPC Server started at 127.0.0.1:9875"，说明通道已就绪：
二、16 个核心工具清单：一张表看懂 AI 能做什么
📋 完整清单如下（工具定义见 docs/tools.md，实现集中在 src/freecad_mcp/server.py）：
| # | 分类 | 工具 | 作用 | 可选截图 |
|---|---|---|---|---|
| 1 | 文档管理 | create_document | 新建 FreeCAD 文档 | ❌ |
| 2 | 文档管理 | list_documents | 列出当前打开的文档 | ❌ |
| 3 | 文档管理 | reload_document | 重新加载文档，同步外部脚本保存的文件变更 | ❌ |
| 4 | 对象操作 | create_object | 创建对象，支持 Part、PartDesign、Fem 等类型 | ✅ |
| 5 | 对象操作 | edit_object | 修改对象的属性 | ✅ |
| 6 | 对象操作 | delete_object | 删除对象 | ✅ |
| 7 | 对象操作 | get_objects | 获取文档中所有对象 | ✅ |
| 8 | 对象操作 | get_object | 获取单个对象的属性详情 | ✅ |
| 9 | 视图检查 | get_view | 获取当前视图截图（9 种视角，可指定尺寸） | ✅ |
| 10 | 代码执行 | execute_code | 在 FreeCAD GUI 线程执行 Python（默认 90 秒预算） | ✅ |
| 11 | 代码执行 | execute_code_async | 后台线程跑重计算，用commit()回写文档 | ❌ |
| 12 | 代码执行 | get_async_status | 查询后台任务状态与失败堆栈 | ❌ |
| 13 | 代码执行 | execute_code_headless | 在独立freecadcmd进程中跑脚本，崩溃不影响 GUI | ❌ |
| 14 | 健康检查 | get_rpc_status | 报告 RPC/GUI 调度健康状态与版本一致性 | ❌ |
| 15 | 零件库 | get_parts_list/insert_part_from_library | 查询并插入 FreeCAD 官方零件库中的现成零件 | ✅ |
| 16 | 仿真分析 | run_fem_analysis | 调用 CalculiX 求解器运行 FEM 分析，返回应力与位移摘要 | ✅ |
💡 零件库一行实际包含 2 个工具：
get_parts_list负责查目录，insert_part_from_library负责插入。
截图是 FreeCAD MCP 的一大特色：create_object、execute_code等 8 个工具默认会附带一张模型截图，AI 能"看到"自己的建模结果，从而自我纠错。常用参数：
include_screenshot：默认true，纯计算类步骤可设为false省 token；view_name：可选Isometric、Front、Top、Right等 9 种视角；- 全局加
--only-text-feedback参数可关闭所有可选截图（见 docs/configuration.md）。
三、三种代码执行模式：新手最需要理解的机制
⚡execute_code只是入口，真正体现工程设计的是三种执行模式的分层（详解见 docs/execution.md）：
| 工具 | 运行位置 | 适用场景 |
|---|---|---|
execute_code | FreeCAD GUI 主线程 | 常规建模自动化，默认 90 秒队列 + 执行双预算，慢任务可传timeout（上限 1800 秒） |
execute_code_async | 独立后台线程 | 大布尔运算、放样等重几何计算；文档/视图写入必须通过commit(fn)交回 GUI 线程，避免卡死 |
execute_code_headless | 独立freecadcmd进程 | 可能崩溃的原生 OCCT 操作（螺纹、复杂放样），原生崩溃只终止辅助进程，GUI 与打开的文档安然无恙 |
配套的"仪表盘"：get_async_status查询后台任务（running/done/failed+ 异常堆栈），get_rpc_status在 GUI 线程被卡住时仍能回答，帮你定位是哪个操作"stuck"了。此外，execute_code与execute_code_async共享一个持久脚本命名空间，前一次调用定义的变量后一次还能直接用——这让 AI 可以分步完成复杂建模。
四、FEM 结构分析：一句"跑一下仿真"就够了
📐run_fem_analysis会在已有的Fem::FemAnalysis容器上自动创建SolverCcxTools并运行 CalculiX 求解器，返回最大 von Mises 应力（MPa）、最大/最小位移（mm）、节点数与求解工作目录，默认超时 600 秒。
配合create_object依次创建几何、Fem::MaterialCommon材料、Fem::FemMeshGmsh网格和约束后，整个分析闭环都在对话里完成。项目提供了端到端示例：examples/cantilever_fem.py，构建悬臂梁、跑 CalculiX，并与解析解对比验证。
五、实战演示：自然语言 → 三维零件
🎬 三个官方演示覆盖了 FreeCAD MCP 最典型的能力：
① 设计法兰：AI 对话中逐步建模、倒角、截图确认（即文首动图）。
② 设计玩具车：从零搭建一个含车身、车轮的装配模型：
③ 从 2D 工程图建模：把一张带尺寸的二维图纸直接丢给 AI，它读图、建草图、生成三维实体。输入图纸示例：
建模过程演示：
更多演示与集成示例见 docs/examples.md，仓库还附带了 Google ADK 智能体 和 LangChain / LangGraph 智能体 两套接入代码，可以把 FreeCAD MCP 挂到你自己的 AI Agent 工作流里。
六、快速上手：三步接通 AI 与 FreeCAD
🏁 前置要求：已安装 FreeCAD 与 uv / uvx，MCP Server 需要 Python 3.12+。
第 1 步：安装插件
git clone https://gitcode.com/gh_mirrors/fr/freecad-mcp cd freecad-mcp把addon/FreeCADMCP目录复制到你系统的 FreeCAD 插件目录（最终形成Mod/FreeCADMCP），各平台的目录路径与复制命令见 docs/installation.md。
第 2 步：启动 RPC 服务
重启 FreeCAD → 选择MCP Addon工作台 → 点击工具栏Start RPC Server，状态栏出现监听地址即成功。可在 FreeCAD MCP 菜单中勾选Auto-Start Server实现开机自启。
第 3 步：接入 AI 客户端
在 Claude Desktop 的claude_desktop_config.json中加入：
{ "mcpServers": { "freecad": { "command": "uvx", "args": ["freecad-mcp"] } } }重启客户端，对 AI 说一句"创建一个边长 10 的方盒子"，FreeCAD 里就会出现这个盒子。🎉
七、连接遇到问题？用健康检查工具自救
🩺 排障三板斧：
get_rpc_status：报告 RPC 连通性、GUI 调度健康状态，以及插件与 Server 的版本一致性（version_check为 "ok" 或提示哪一侧需要更新）；- 查看 Report View 的启动日志：端口被占用等失败原因会直接显示，例如：
- 核对两侧版本：插件与
freecad-mcp包独立更新，版本不一致时每次工具响应开头会带警告，告诉你该更新哪一侧；若 GUI 线程卡死（stuck），按 docs/execution.md 的"Recover from a stuck GUI operation"章节处理，必要时重启 FreeCAD。
其他高频问题：
- 远程连接：RPC 服务默认只监听 localhost；跨机器控制需开启 Remote Connections、配置 Allowed IPs 并建议设置 Auth Token，详见 docs/configuration.md；
- 端口验证：用 PowerShell 的
Test-NetConnection或外部 Python 脚本ping()确认 9875 端口背后确实是 FreeCAD 的 XML-RPC 服务； - Windows 客户端报错
uv_spawn：可尝试用cmd /c freecad-mcp方式启动，属客户端层面的兼容处理。
小结
FreeCAD MCP 的价值，是把"会写 Python"这个门槛从 AI 建模的必经之路上拿掉了：16 个工具覆盖文档、对象、视图、代码、零件库与 FEM 全流程，三种执行模式兼顾了安全性与性能，再加上截图反馈，AI 能看、能做、能查错。装好插件、连上客户端，你就可以像布置工作一样对 FreeCAD 说话了。
📚 延伸阅读：安装指南 · 配置说明 · 工具清单 · 代码执行详解 · 演示与示例
【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
