基于MCP协议实现Claude AI与FreeCAD智能交互：自然语言驱动3D设计自动化

在CAD设计工作中我们常常需要反复执行一些重复性的建模、参数调整或数据查询任务这不仅耗时耗力还容易因疲劳而出错。如果能有一个智能助手通过自然语言对话就能帮我们完成这些操作无疑将极大提升设计效率。本文将手把手教你如何将强大的Claude AI与开源3D CAD软件FreeCAD连接起来通过Model Context ProtocolMCP实现智能交互。无论你是想自动化参数化设计、快速生成复杂几何体还是希望通过对话管理模型数据这套方案都能让你像与资深工程师协作一样使用FreeCAD。1. 核心概念什么是MCP及其价值在深入实操之前我们首先要理解本次集成的技术核心——Model Context ProtocolMCP。这不仅是实现连接的关键更代表了一种全新的AI应用范式。1.1 MCPAI与工具对话的“通用语言”Model Context Protocol模型上下文协议可以理解为AI模型如Claude与外部工具、应用程序或数据源进行安全、结构化通信的一套标准和框架。它不是一个具体的软件而是一组协议和规范。为什么需要MCP传统的AI助手虽然能处理文本但无法直接“操作”你电脑上的具体软件比如打开FreeCAD并创建一个立方体。MCP充当了“翻译官”和“安全员”的双重角色翻译功能将你的自然语言指令如“在FreeCAD中创建一个长50mm、宽30mm、高20mm的长方体”转换为FreeCAD API能理解的精确命令。安全沙箱为AI访问你的软件和数据设定严格的边界和权限防止其执行危险操作如任意删除文件。1.2 Claude FreeCAD MCP 能做什么三者结合后你的工作流将发生质变自然语言建模直接描述你想要的形状和尺寸AI帮你生成精确的Python脚本并在FreeCAD中执行。智能参数调整对话式修改模型参数“把那个孔的直径从5mm改成8mm”无需手动定位和输入。设计查询与分析询问模型的质量、体积、重心或让AI检查模型是否存在干涉。流程自动化将一系列重复操作如创建一系列按规则排列的孔编写成自动化脚本。学习与探索不熟悉FreeCAD API直接问AI“如何使用Python在FreeCAD中画一条螺旋线”这套组合拳的核心价值在于降低了专业CAD软件的操作门槛并将设计师从重复劳动中解放出来专注于更高层的创意和决策。2. 环境准备与工具版本说明成功的集成始于稳定、兼容的环境。以下是经过验证的环境配置请尽量遵循以确保流程顺畅。2.1 主要软件及版本要求组件推荐版本说明获取方式FreeCAD0.21.2 (或更高稳定版)开源3D CAD软件本次集成的“被操作对象”。从 FreeCAD官网 下载安装。Python3.9 - 3.11FreeCAD内置Python但独立安装可确保MCP服务器环境纯净。从 Python官网 下载。安装时务必勾选“Add Python to PATH”。Node.js18.x 或 20.x LTS运行Claude Desktop及MCP服务器的JavaScript环境。从 Node.js官网 下载LTS版本。Claude Desktop最新版Anthropic官方客户端内置MCP客户端支持。从 Claude官网 下载。Git最新版用于克隆MCP服务器仓库。从 Git官网 下载。版本兼容性关键点FreeCAD 0.21 对Python API的支持更完善是必须的。Python 3.12 可能与某些依赖库存在兼容性问题建议暂时使用3.11。安装Node.js后请打开终端CMD/PowerShell/Terminal运行node --version和npm --version确认安装成功。2.2 项目结构预览在开始前我们先规划好工作目录保持文件组织清晰claude_freecad_integration/ ├── freecad_mcp_server/ # MCP服务器项目目录 │ ├── src/ │ ├── package.json │ └── ... ├── scripts/ # 存放自定义FreeCAD Python脚本 │ └── custom_operations.py └── readme.md # 项目说明可选建议在桌面或文档目录下创建名为claude_freecad_integration的文件夹后续所有操作都在此进行。3. 核心组件搭建MCP服务器原理与初始化MCP服务器是连接Claude和FreeCAD的桥梁。我们将使用一个开源社区项目作为基础进行配置。3.1 理解MCP服务器的工作原理MCP服务器本质上是一个长期运行的后台进程它主要做三件事监听请求通过标准输入输出(stdin/stdout)或网络Socket接收来自Claude DesktopMCP客户端的JSON-RPC格式请求。执行操作解析请求调用对应的工具函数。在我们的场景中就是调用FreeCAD的Python API。返回结果将操作结果成功信息、生成的数据、错误提示封装成JSON-RPC格式返回给Claude。一个简单的“获取FreeCAD版本”工具调用流程如下你 - “FreeCAD版本是多少” - Claude Claude - (JSON-RPC请求) - MCP服务器 MCP服务器 - FreeCAD.Version() - FreeCAD FreeCAD - ‘0.21.2’ - MCP服务器 MCP服务器 - (JSON-RPC响应) - Claude Claude - “FreeCAD版本是0.21.2。” - 你3.2 获取并配置MCP服务器我们将使用一个社区开发的freecad-mcp-server项目。请打开终端执行以下步骤。步骤一克隆服务器代码库# 进入你之前创建的项目根目录 cd ~/Documents/claude_freecad_integration # 克隆仓库请使用以下可用仓库之一 git clone https://github.com/your-username/freecad-mcp-server.git freecad_mcp_server # 注如果上述仓库不存在你可能需要搜索 freecad mcp server 寻找其他开源实现。 # 本教程假设仓库结构包含src、package.json等文件。 cd freecad_mcp_server步骤二安装Node.js依赖# 安装项目运行所需的所有npm包 npm install此命令会根据package.json文件安装所有依赖包括与FreeCAD通信的库。步骤三配置FreeCAD路径关键步骤MCP服务器需要知道如何启动FreeCAD的Python解释器。通常FreeCAD安装后会自带一个python.exeWindows或python可执行文件Mac/Linux。Windows 典型路径默认安装C:\Program Files\FreeCAD 0.21\bin\python.exe便携版你的路径\FreeCAD\bin\python.exemacOS 典型路径/Applications/FreeCAD.app/Contents/Resources/bin/python3Linux 典型路径通过包管理器安装后通常freecadcmd或freecad命令已包含Python环境。你需要创建一个配置文件来指明路径。在freecad_mcp_server目录下创建或修改一个名为.env的文件# .env 文件内容示例 (Windows) FREECAD_PYTHON_PATHC:\\Program Files\\FreeCAD 0.21\\bin\\python.exe # .env 文件内容示例 (macOS) FREECAD_PYTHON_PATH/Applications/FreeCAD.app/Contents/Resources/bin/python3 # .env 文件内容示例 (Linux - 如果使用AppImage) FREECAD_PYTHON_PATH/path/to/FreeCAD.AppImage重要Windows路径中的反斜杠\需要转义为\\或者使用正斜杠/。3.3 测试MCP服务器连接在启动Claude配置之前我们先独立测试服务器是否能与FreeCAD正常通信。步骤一启动测试FreeCAD Python环境在终端中尝试直接运行FreeCAD的Python# Windows (在CMD或PowerShell中) C:\Program Files\FreeCAD 0.21\bin\python.exe -c import FreeCAD; print(FreeCAD.Version()) # macOS/Linux /Applications/FreeCAD.app/Contents/Resources/bin/python3 -c import FreeCAD; print(FreeCAD.Version())如果成功输出类似[0,21,2,Git (xxxx)]的版本信息说明FreeCAD Python环境可用。步骤二运行MCP服务器进行测试在freecad_mcp_server目录下运行npm start # 或根据package.json中的脚本可能是node src/index.js如果服务器启动成功通常会输出类似MCP server started on stdio的日志并等待连接。此时你可以按CtrlC停止它因为我们接下来要在Claude中配置它。4. 配置Claude Desktop集成MCP服务器这是让Claude“认识”并能够调用我们刚刚搭建的MCP服务器的关键一步。4.1 定位Claude Desktop配置目录Claude Desktop通过一个配置文件来加载MCP服务器。配置文件的位置因操作系统而异Windows%APPDATA%\Claude\claude_desktop_config.json具体路径通常为C:\Users\你的用户名\AppData\Roaming\Claude\claude_desktop_config.jsonmacOS~/Library/Application Support/Claude/claude_desktop_config.jsonLinux~/.config/Claude/claude_desktop_config.json如果该文件或目录不存在你需要手动创建。4.2 编写Claude Desktop配置文件用文本编辑器如VS Code、Notepad打开或创建上述路径的claude_desktop_config.json文件。重要在修改前请完全退出Claude Desktop应用程序。将以下配置内容填入该文件。你需要将command中的路径替换为你实际的node命令和项目路径。{ mcpServers: { freecad: { command: node, args: [ /绝对/路径/到/你的/claude_freecad_integration/freecad_mcp_server/src/index.js ], env: { FREECAD_PYTHON_PATH: C:\\Program Files\\FreeCAD 0.21\\bin\\python.exe } } } }参数详解与路径替换command: node指定使用Node.js来运行我们的服务器脚本。args数组中的第一个元素是MCP服务器主入口文件的绝对路径。如何获取绝对路径Windows在文件资源器中找到index.js按住Shift键并右键点击它选择“复制为路径”然后粘贴到这里并将路径引号改为双引号。macOS/Linux在终端中进入freecad_mcp_server目录运行pwd获取绝对路径然后拼接上/src/index.js。env这里的环境变量会传递给MCP服务器进程。FREECAD_PYTHON_PATH必须与你在.env文件中设置的一致。如果服务器能从系统PATH找到FreeCAD有时可以省略。macOS/Linux配置示例{ mcpServers: { freecad: { command: node, args: [ /Users/username/Documents/claude_freecad_integration/freecad_mcp_server/src/index.js ], env: { FREECAD_PYTHON_PATH: /Applications/FreeCAD.app/Contents/Resources/bin/python3 } } } }4.3 启动与验证连接保存配置文件确保claude_desktop_config.json文件已正确保存。启动Claude Desktop像平常一样打开Claude Desktop应用。创建新对话建议开启一个新的对话窗口进行测试。验证工具加载在输入框附近或Claude的回复中寻找工具提示。如果配置成功你可能会看到一个螺丝刀/扳手图标️。Claude的回复开头包含“我已连接FreeCAD工具...”等字样。最直接的验证方法是直接询问Claude“你有哪些可用的工具”或“你能使用FreeCAD吗”。如果配置成功它会列出可用的FreeCAD相关工具如create_box,get_version,list_objects等。5. 完整实战从对话到3D模型生成现在激动人心的时刻到了。我们将通过几个完整的例子演示如何用自然语言驱动FreeCAD创建和修改3D模型。5.1 基础实战创建一个参数化长方体你的指令“在FreeCAD中创建一个新的文档然后添加一个长方体长度50毫米宽度30毫米高度20毫米并将其命名为‘MyBox’。”Claude可能执行的操作幕后调用MCP工具create_box或类似工具。传递参数{“length”: 50, “width”: 30, “height”: 20, “name”: “MyBox”}。MCP服务器接收请求执行类似以下的Python代码import FreeCAD, Part doc FreeCAD.newDocument() # 或获取当前活动文档 box doc.addObject(“Part::Box”, “MyBox”) box.Length ‘50 mm’ box.Width ‘30 mm’ box.Height ‘20 mm’ doc.recompute()操作成功后Claude会回复你“已完成已在FreeCAD中创建了名为‘MyBox’的长方体尺寸为50x30x20 mm。你现在可以在FreeCAD的3D视图中看到它。”请在FreeCAD中验证打开FreeCAD桌面应用程序。你应该能看到一个新文档并且在左侧的“模型树”中有一个名为“MyBox”的对象。3D视图区显示一个长方体。你可以选中“MyBox”在下方的“属性”面板中查看和修改其尺寸参数。5.2 进阶实战修改模型与添加特征你的指令“在刚才创建的长方体上表面中心打一个通孔直径10毫米。”Claude可能执行的操作 这涉及更复杂的布尔运算。Claude需要在长方体上表面中心创建一个圆柱体作为“刀具”。使用Part Cut布尔减运算从长方体中“减去”这个圆柱体。执行的Python逻辑会更复杂需要计算中心位置。# 简化逻辑示意 cylinder doc.addObject(“Part::Cylinder”, “HoleCutter”) cylinder.Radius ‘5 mm’ # 直径10mm cylinder.Height box.Height # 确保贯通 # 计算并设置圆柱体的位置使其位于上表面中心 cylinder.Placement.Base (box.Length/2, box.Width/2, box.Height) # 执行布尔减运算 cut doc.addObject(“Part::Cut”, “BoxWithHole”) cut.Base box cut.Tool cylinder doc.recompute()Claude回复“已在‘MyBox’上添加了一个直径为10mm的通孔。”5.3 查询与分析实战你的指令“帮我计算一下当前模型中这个带孔长方体的体积和质量假设材料是铝密度2.7 g/cm³。”Claude可能执行的操作调用get_object_properties或calculate_volume工具。MCP服务器通过FreeCAD API获取模型的体积属性。shape cut.Shape # 获取布尔运算后的形状 volume shape.Volume # 单位是mm³ volume_cm3 volume / 1000.0 mass_g volume_cm3 * 2.7 # 密度换算Claude回复“该模型的体积约为 29,500 mm³29.5 cm³。按铝密度计算质量约为 79.65 克。”通过以上实战你可以看到从基础建模到特征修改再到物理属性分析整个过程都可以通过对话流畅完成。6. 常见问题与详细排查指南集成过程中遇到问题很正常。请根据以下清单按顺序排查。6.1 Claude无法识别FreeCAD工具问题现象可能原因排查步骤与解决方案启动Claude后无工具图标询问Claude后它表示没有可用工具。1. 配置文件路径错误。2. 配置文件格式错误JSON语法。3. Claude Desktop未读取新配置。1.检查路径确认claude_desktop_config.json文件在正确的操作系统目录下。2.验证JSON将配置文件内容复制到 JSONLint 等在线工具检查语法。3.重启Claude完全退出Claude Desktop包括系统托盘图标再重新启动。4.查看日志在Claude Desktop设置中或通过命令行启动时查看是否有MCP加载错误日志。Claude识别到工具但工具列表中没有FreeCAD相关项。1. MCP服务器启动失败。2.command或args路径不正确。3. Node.js环境或项目依赖问题。1.手动测试服务器在终端中进入MCP服务器目录运行npm start。观察是否有错误输出。2.检查Node路径在终端输入where node(Win) 或which node(Mac/Linux)确保command指向正确的node可执行文件或直接使用系统路径“node”。3.检查入口文件确认args中的index.js文件路径绝对正确且文件存在。4.重装依赖在MCP服务器目录下删除node_modules文件夹和package-lock.json重新运行npm install。6.2 MCP服务器启动失败或报错问题现象可能原因排查步骤与解决方案运行npm start时报错提示模块找不到Cannot find module。1. 依赖未安装。2. Node.js版本不兼容。3. 项目文件损坏。1.安装依赖确保已运行npm install。2.切换Node版本尝试使用Node.js 18或20的LTS版本。可使用nvmNode Version Manager管理多版本。3.重新克隆项目。服务器启动后立即退出或提示FreeCAD相关错误。1.FREECAD_PYTHON_PATH环境变量错误。2. FreeCAD未安装或版本太低。3. FreeCAD的Python环境缺少某些模块。1.验证FreeCAD Python路径在终端中尝试用配置的路径直接运行Python并导入FreeCAD见3.3节测试步骤。2.检查FreeCAD版本确保安装的是0.21或更高版本。3.使用完整路径在.env文件和Claude配置中均使用FreeCAD Python解释器的绝对路径。出现权限错误Permission denied。1. 文件或目录权限不足。2. 防病毒软件或系统策略阻止。1.以管理员/特权模式运行终端Windows或使用sudoLinux/macOS但不推荐注意安全。2.检查文件权限确保当前用户对MCP服务器项目目录有读写执行权限。3.暂时关闭防病毒软件测试是否为拦截导致。6.3 工具调用成功但FreeCAD无反应问题现象可能原因排查步骤与解决方案Claude回复“操作成功”但FreeCAD界面中没有出现新模型。1. FreeCAD未以前台或后台模式运行。2. MCP服务器操作的是另一个FreeCAD实例或隐藏实例。3. 文档未正确创建或激活。1.启动FreeCAD GUI确保FreeCAD桌面应用程序已经打开。部分MCP服务器实现需要GUI运行时环境。2.检查活动文档在FreeCAD中查看“文件”菜单下是否有未命名的“未命名”文档被创建。尝试点击“模型树”中的“刷新”或按F5键。3.查看报告视图FreeCAD下方的“报告视图”或“Python控制台”是否有错误信息。FreeCAD中模型已创建但位置、尺寸不对。1. 坐标系统理解差异。2. 单位转换问题。1.明确指令给Claude的指令应尽可能精确例如“在原点(0,0,0)创建...”。2.指定单位始终在指令中明确单位如mm, cm。虽然FreeCAD内部使用mm但明确指定有助于AI理解。3.分步操作对于复杂操作先让AI创建基础形状再分步添加特征。7. 最佳实践与高级工程建议为了让这套工作流更稳定、高效、安全地服务于你的实际项目请遵循以下建议。7.1 安全与稳定性第一操作前保存在让AI执行任何可能修改现有模型的复杂操作如布尔切割、阵列前务必先在FreeCAD中手动保存CtrlS你的工程文件。AI操作虽便捷但无法完全替代人类对设计意图的判断。使用版本控制对于重要的设计项目将FreeCAD的.FCStd文件纳入Git等版本控制系统。在让AI进行重大修改前进行一次提交以便随时回退。限制工具范围如果你有能力修改MCP服务器的代码可以考虑只暴露你常用且安全的工具给Claude禁用如close_document不保存关闭或delete_object等高风险操作或为其添加确认机制。环境隔离考虑为AI辅助设计创建单独的FreeCAD配置或用户目录避免核心设置被意外修改。7.2 提升指令效率与准确性结构化描述清晰的指令能得到更好的结果。例如不佳“做个架子。”优秀“创建一个新的Part Design Body。在其XY平面上创建一个草图画一个长200mm、宽100mm的矩形。将此矩形向上拉伸Pad20mm生成一个实体并命名为‘ShelfBase’。”分步进行对于复杂模型采用“创建-修改-查询”的循环。先让AI创建主体再逐步添加孔、倒角、阵列等特征。每步完成后在FreeCAD中检查结果。利用上下文Claude能记住对话历史。你可以说“在刚才创建的那个长方体的侧面...”而无需重复所有参数。结合使用将AI生成复杂特征如齿轮、弹簧的代码与你手动进行的精细调整如装配约束、工程图标注相结合发挥各自优势。7.3 扩展MCP服务器功能开源MCP服务器项目通常只实现了基础功能。你可以通过修改其源代码来扩展工具集这是发挥其最大威力的关键。示例添加一个“创建螺栓阵列”的自定义工具定位工具定义文件在MCP服务器项目中例如src/tools/freecadTools.js或类似文件找到工具注册的地方。添加新工具函数// 假设使用Node.js这是一个简化的示例框架 async function createBoltArray(params) { const { documentName, centerX, centerY, numBolts, boltRadius, circleRadius } params; // 构造要发送给FreeCAD Python端的命令 const pythonCode import FreeCAD, Part, Draft doc FreeCAD.getDocument(${documentName}) for i in range(${numBolts}): angle (360/${numBolts}) * i rad math.radians(angle) x ${centerX} ${circleRadius} * math.cos(rad) y ${centerY} ${circleRadius} * math.sin(rad) cylinder doc.addObject(Part::Cylinder, fBolt_{i}) cylinder.Radius ${boltRadius} cylinder.Height 10 cylinder.Placement.Base FreeCAD.Vector(x, y, 0) doc.recompute(); // 调用执行Python代码的通用函数 const result await executeFreeCADPython(pythonCode); return { success: true, message:Created ${numBolts} bolts in a circle. }; }3. **注册工具**在工具列表中注册这个新函数定义其输入参数schema。javascript { name: “create_bolt_array”, description: “在指定圆心创建一圈螺栓阵列”, inputSchema: { type: “object”, properties: { documentName: { type: “string” }, centerX: { type: “number”, default: 0 }, centerY: { type: “number”, default: 0 }, numBolts: { type: “number”, minimum: 1 }, boltRadius: { type: “number”, minimum: 0.1 }, circleRadius: { type: “number”, minimum: 0 } }, required: [“documentName”, “numBolts”, “boltRadius”, “circleRadius”] }, handler: createBoltArray } 4.重启服务器并测试重启MCP服务器和Claude Desktop然后你就可以对Claude说“使用‘create_bolt_array’工具在当前文档中以原点(0,0)为圆心创建8个半径为2mm的螺栓分布圆半径为50mm。”通过这种方式你可以将任何重复性的、流程化的FreeCAD操作封装成AI可调用的工具真正实现设计自动化。将Claude AI通过MCP协议连接到FreeCAD不仅仅是多了一个语音控制界面而是引入了一个能够理解设计意图、执行精确操作、并具备一定计算推理能力的数字助手。从环境配置、服务器调试到实战指令本教程提供了闭环的解决方案。初期可能会遇到环境配置的挑战但一旦打通你将获得一个强大的、可扩展的智能CAD工作流。建议从简单的几何体创建开始逐步尝试更复杂的参数化设计和分析任务并积极探索扩展自定义工具使其完全适配你的专业领域和工作习惯。