FreeCAD MCP Server

对于从事 CAD 设计、机械工程和 3D 建模的专业人士来说，FreeCAD 是一个强大而灵活的开源平台。然而，复杂的参数化建模操作常常意味着需要记忆大量的菜单路径、工作台切换和精确的鼠标操作。现在，想象一下你只需用自然语言告诉 AI 助手“创建一个 50x30x20mm 的立方体，并在顶部中心打一个直径 10mm 的通孔”——FreeCAD MCP Server 正是让这一切成为现实的桥梁。它将 AI 的语义理解能力直接注入 FreeCAD，开启了语音和文本驱动的参数化建模新范式。

项目基本信息

信息项	详情
项目名称	FreeCAD MCP Server
GitHub 地址	https://github.com/neka-nat/freecad-mcp
项目描述	通过 Claude Desktop 控制 FreeCAD 的 MCP 服务器，支持创建文档、3D 对象、执行 Python 代码和插入零件库
作者	neka-nat
开源协议	MIT License
开源状态	公开状态
Languages	Python
支持平台	Windows / macOS / Linux
最后更新	2025-06-06

一、项目介绍

FreeCAD MCP Server 由两个关键组件构成，形成一个完整的“AI 驱动 CAD”工作流：

FreeCAD 插件：安装在 FreeCAD 内部，启动一个 RPC 服务器，将 FreeCAD 内部的建模能力暴露为可远程调用的接口。
MCP 服务器：运行在 Claude Desktop 侧，将 AI 的自然语言指令翻译为对 FreeCAD 插件的 RPC 调用。

核心工具集

该服务器提供了 10 个 MCP 工具，覆盖了从文档创建到精细 3D 操作的全流程：

工具	功能	使用场景
`create_document`	在 FreeCAD 中创建新文档	开始一个新设计项目
`create_object`	创建新的 3D 对象（立方体、圆柱等）	构建基本几何体
`edit_object`	编辑现有对象的参数	调整对象的尺寸、位置等
`delete_object`	删除指定对象	修改设计时移除不需要的几何体
`execute_code`	在 FreeCAD 中执行任意 Python 代码	进行复杂、定制化的建模操作
`insert_part_from_library`	从零件库中插入标准件	添加螺栓、螺母等常用零件
`get_view`	获取当前活动视图的截图	视觉检查建模结果
`get_objects`	列出文档中的所有对象	查看当前设计包含哪些几何体
`get_object`	获取特定对象的详细信息	查询某个对象的参数和位置
`get_parts_list`	获取零件库中的可用零件列表	AI 了解可用的标准件

二、核心优势

自然语言驱动的参数化建模

这是 FreeCAD MCP Server 最具革命性的价值。你不再需要记忆“先切换到 Part 工作台，再点击立方体图标，然后在属性面板中输入尺寸”。只需要说出你的意图，AI 就会自动完成一系列操作。例如：“创建一个外径 100mm、内径 80mm、高度 50mm 的空心圆柱”。

Python 代码执行的灵活性

execute_code 工具赋予了高级用户无限的扩展能力。AI 可以直接运行 FreeCAD 的 Python API 来实现复杂建模——包括参数化草图、约束施加、特征创建等。这既适合新手（AI 生成代码），也适合专家（可以验证和修改 AI 生成的 Python 脚本）。

零件库集成

insert_part_from_library 和 get_parts_list 工具让 AI 能直接访问 FreeCAD 的标准件库。当你的设计需要螺栓、螺母或轴承等常用零件时，AI 可以自动搜索并插入合适的标准件，省去了手动查找和导入的时间。

视觉反馈循环

AI 通过 get_view 工具获取当前 3D 视图的截图。它能看到自己创建的几何体是否符合预期，并根据视觉反馈进行调整。这是一个关键的闭环验证能力，使 AI 不只是在执行命令，而是在“观察-调整”中迭代。

MIT 开源协议

采用完全商业友好的 MIT 协议，适合工程师、设计师和教育工作者自由使用。

三、适用场景

快速原型设计

用户：创建一个 100x80mm 的矩形板，在四个角各打一个直径 5mm 的孔。

AI 创建主体板，然后计算四个角的坐标，在每个角放置一个圆柱体用于布尔减法运算。你通过截图确认设计后，继续提出修改要求。

教育培训

教师：展示如何创建一个参数化的齿轮。

AI 执行相应的 Python 代码，创建一个齿轮模型。学生观察 FreeCAD 界面同步看到几何体的生成，AI 同时解释每一步的作用。

标准件自动装配

用户：我需要一个 M8x30 的六角螺栓。

AI 从零件库中搜索 M8x30 螺栓并插入到当前文档中。

Python 脚本辅助学习

新手：帮我写一段 Python 代码，创建一个参数化的旋转体。

AI 使用 FreeCAD 的 Part 模块编写 Python 脚本并执行。你可以读取生成的脚本，学习 FreeCAD 的 Python API 使用方式。

从 2D 图纸生成 3D 模型

用户：把这张 2D 草图转换为 3D 模型。

AI 分析 2D 图纸中的几何信息，使用 FreeCAD 的拉伸或旋转操作创建 3D 实体。

四、安装教程

环境要求

工具	用途	版本要求
FreeCAD	CAD 平台	任何支持插件的版本
Python	运行 MCP 服务器	3.8+
uvx	Python 应用运行器	最新版
Claude Desktop	MCP 客户端	已安装

安装步骤

第一步：安装 FreeCAD 插件

找到 FreeCAD 插件目录：
- Windows: %APPDATA%\FreeCAD\Mod\
- macOS: ~/Library/Application Support/FreeCAD/Mod/
- Linux (Ubuntu): ~/.FreeCAD/Mod/ 或 ~/snap/freecad/common/Mod/
- Linux (Debian): ~/.local/share/FreeCAD/Mod

克隆仓库并复制插件文件：

git clone https://github.com/neka-nat/freecad-mcp.git
cd freecad-mcp
cp -r addon/FreeCADMCP ~/.FreeCAD/Mod/

重启 FreeCAD。
在 FreeCAD 中，从工作台列表中选择 “MCP插件”，然后点击 “启动RPC服务器”。

第二步：配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），添加：

对于用户：

{
  "mcpServers": {
    "freecad": {
      "command": "uvx",
      "args": ["freecad-mcp"]
    }
  }
}

仅使用文本反馈（不获取截图，节省令牌）：

{
  "mcpServers": {
    "freecad": {
      "command": "uvx",
      "args": ["freecad-mcp", "--only-text-feedback"]
    }
  }
}

对于开发者：

git clone https://github.com/neka-nat/freecad-mcp.git

{
  "mcpServers": {
    "freecad": {
      "command": "uv",
      "args": ["--directory", "/path/to/freecad-mcp/", "run", "freecad-mcp"]
    }
  }
}

第三步：启动集成

启动 FreeCAD，确保 RPC 服务器已启动。
重启 Claude Desktop。

五、使用示例

示例一：创建基础几何体

用户：在 FreeCAD 中创建一个立方体，边长 50mm。

AI 调用 create_document 创建新文档，然后调用 create_object，传入 type="cube" 和 params={"length": 50}。

用户：这个立方体太大了，改成 30mm。

AI 调用 edit_object，修改该对象的长度参数为 30。

示例二：复杂建模

用户：创建一个外径 50mm、内径 20mm、高度 100mm 的管道。

AI 使用 Python 代码创建两个同心圆柱体，然后执行布尔减法运算，生成管道。

示例三：从零件库插入标准件

用户：帮我往当前文档插入一个 M6 的六角螺母。

AI 先调用 get_parts_list 查看可用标准件，然后调用 insert_part_from_library(name="hex_nut_m6") 插入螺母。

示例四：视觉验证与迭代

用户：让我看看现在模型是什么样子。

AI 调用 get_view 获取截图，显示在对话中。

用户：孔太靠近边缘了，把距边缘的距离增加到 10mm。

AI 调用 edit_object 调整孔的位置参数，然后再次调用 get_view 确认修改效果。

六、常见问题

问：Claude Desktop 提示“无法连接到 FreeCAD”？

答：请确保：

FreeCAD 已启动，并已安装 MCP 插件。
在 FreeCAD 中已选择“MCP插件”工作台，并点击了“启动RPC服务器”。
RPC 服务器的端口（默认在插件中显示）未被防火墙阻止。

问：execute_code 可以执行任意的 FreeCAD Python 代码吗？

答：是的，这在带来极大灵活性的同时也需要谨慎。AI 生成的代码可能存在错误或不符合你的意图。建议在使用 execute_code 前，先在单独的 FreeCAD 实例中测试，或让 AI 先解释其计划执行的代码。

问：--only-text-feedback 参数的作用是什么？

答：启用此参数后，get_view 工具将不会返回截图。这可以节省 MCP 通信的令牌消耗，适合仅需文本描述的场景，或使用的 Claude 版本不支持多模态输入时。

问：零件库包含哪些标准件？

答：零件库内容取决于你的 FreeCAD 安装。AI 可以通过 get_parts_list 工具获取完整列表，通常包含螺栓、螺母、垫圈、轴承等常用标准件。

问：可以在同一个 FreeCAD 会话中处理多个文档吗？

答：可以。使用 create_document 创建新文档，并通过 AI 使用不同的文档引用进行切换。

七、总结

FreeCAD MCP Server 将 AI 的语义理解能力与 CAD 的精确建模能力创造性地结合在了一起。它不只让 FreeCAD 变得更容易上手，更开创了一种“所想即所得”的设计新范式——你用自然语言描述设计意图，AI 将其转化为精确的 3D 几何体。

对于工程师、设计师和教育工作者来说，这意味着可以大幅减少记忆菜单操作的时间，将更多思维集中在创意设计本身。而对于开源硬件和 DIY 社区，这个工具让 3D 建模的门槛降到了前所未有的低点。花半小时完成安装配置，你会发现用对话来创作 3D 模型的体验，如同拥有了一位精通 FreeCAD 的数字助手。

登录

注册账号