你有没有试过在 CAD 软件里一边画图一边和 AI 助手讨论设计思路让它帮你生成参数、计算尺寸甚至直接修改模型这听起来像是科幻电影里的场景但今天通过一个名为MCPModel Context Protocol的协议我们可以把强大的 Claude AI 直接“安装”到 FreeCAD 这个开源三维建模软件里让它从一个被动的问答工具变成一个能理解你当前工作上下文、并能直接操作软件的“智能副驾驶”。这不仅仅是“让 AI 帮你写代码”那么简单。想象一下你正在设计一个零件可以直接问 Claude“这个孔的直径需要满足 M6 螺栓的安装要求帮我计算并设置一下。” 或者你画了一个草图但不确定约束是否完全可以让 Claude 检查并报告缺失的约束。甚至你可以让它基于现有模型自动生成一份 BOM物料清单或加工说明。整个过程AI 能“看到”你正在操作的 FreeCAD 文档理解其中的几何体、参数和约束并执行精确的操作。然而把两个独立的工具——云端 AI 和本地桌面软件——无缝连接起来中间涉及协议、服务器、认证和 API 调用对大多数设计师和工程师来说门槛不低。网上的教程往往只讲了一半或是版本过时导致跟着操作总是卡在某个步骤最终只能放弃。本文将为你提供一个完整、可验证、亲测有效的 MCP 设置教程。我不会只告诉你“去装个 MCP 服务器”而是会带你从零开始理解 MCP 是什么、为什么需要它、以及如何一步步搭建起 Claude Desktop 与 FreeCAD 之间的桥梁。更重要的是我会分享在配置过程中最容易踩坑的几个地方以及如何验证连接是否真正成功。我们的目标不是简单地复制命令而是让你掌握这套工作流的底层逻辑从而能举一反三未来甚至可以连接其他支持 MCP 的工具。1. 先搞懂 MCP它如何让 AI 从“聊天框”变成“操作手”在开始敲命令之前我们必须先理解核心问题为什么普通的 AI 聊天无法直接操作 FreeCAD而 MCP 又是如何解决这个问题的1.1 传统 AI 交互的局限盲人摸象你平时使用 Claude 或 ChatGPT基本模式是你在聊天框里输入一段文字描述AI 基于它的训练数据生成一段文字回复。如果你想让它处理 FreeCAD 相关任务你只能用文字描述你的模型“我有一个长方体长100mm宽50mm高20mm上面有一个通孔……”用文字描述你的需求“请为我生成创建这个模型的 Python 宏代码。”AI 回复一段代码。你手动复制这段代码打开 FreeCAD 的 Python 控制台粘贴并运行。如果出错你再把错误信息复制回聊天框继续循环。这个过程存在几个致命问题信息损失严重用文字描述复杂三维模型效率极低且容易出错。缺乏上下文AI 完全不知道你当前 FreeCAD 文档里到底有什么正在编辑哪个对象选择了哪些面。操作不直接需要“生成代码 - 用户执行代码”的二次转换无法实现“对话即操作”。本质上AI 是在“盲猜”你是在“传话”。1.2 MCP 的核心思想为 AI 安装“眼睛”和“手”MCPModel Context Protocol是由 Anthropic 公司提出的一种开放协议。你可以把它理解为AI 的“外设驱动”标准。它的目标很明确让 AI 模型能够安全、结构化地访问和使用各种工具、数据源和应用程序。在 FreeCAD 这个场景下MCP 扮演了以下角色翻译官协议定义了一套 Claude AI 能理解的“语言”API用于描述和操作 FreeCAD 中的对象如文档、物体、草图、约束。本地代理服务器一个运行在你电脑上的小型程序MCP 服务器。它一方面通过 MCP 协议与 Claude Desktop 通信另一方面通过 FreeCAD 的 Python API 直接与 FreeCAD 交互。安全通道连接在 Claude Desktop 和本地 MCP 服务器之间建立一条安全的通信链路使得 Claude 可以发送指令并接收来自 FreeCAD 的实时状态反馈。实现的效果是当你在 Claude Desktop 中输入“列出当前文档中的所有物体”时这条消息会通过 MCP 协议发送给你的本地 FreeCAD MCP 服务器。服务器随即调用FreeCAD.ActiveDocument.Objects获取列表再通过协议格式返回给 Claude。Claude 就能“看到”并回复你“当前文档中有 ‘Box’ ‘Cylinder’ 两个物体。”至此AI 有了“眼睛”能读取状态。同样它也能通过服务器调用 API 来创建、修改、删除对象从而拥有了“手”。1.3 关键组件与工作流全景图为了让你对整体架构有清晰的认识我们先俯瞰整个系统是如何协作的[你] --对话-- [Claude Desktop 应用] --MCP 协议HTTP/Stdio-- [FreeCAD MCP 服务器] --Python API-- [FreeCAD 软件]Claude Desktop这是 Anthropic 官方的桌面客户端。它内置了 MCP 客户端功能可以配置并连接多个 MCP 服务器。MCP 服务器FreeCAD 专用这是一个独立的 Python 脚本或程序。它持续运行监听来自 Claude Desktop 的请求。你需要安装它。FreeCAD必须正在运行并且打开了你要操作的文档。MCP 服务器通过FreeCAD这个 Python 模块与它交互。配置文件告诉 Claude Desktop 去哪里、用什么方式连接你的 MCP 服务器。理解了这个架构你就会明白后续所有步骤都是在搭建和配置这条通信链路。任何一个环节断裂整个系统就无法工作。2. 搭建前的准备理清环境与依赖避免第一步就卡住很多教程失败是因为忽略了环境兼容性这个“暗礁”。不同操作系统、不同版本的软件配置方法可能有细微差别。本节将帮你扫清这些前期障碍。2.1 软件清单与版本确认请确保你已安装以下软件并尽量使用推荐的版本以最大化兼容性。组件推荐版本作用获取方式FreeCAD0.21.2 或更高版本三维 CAD 软件被操作的对象FreeCAD 官网Python3.8 - 3.11 (与 FreeCAD 内置版本匹配为佳)运行 MCP 服务器和 FreeCAD API系统自带或从 Python.org 下载Claude Desktop最新版AI 客户端MCP 的发起方Anthropic 官网Git最新版克隆 MCP 服务器代码仓库Git 官网FreeCAD MCP Server社区维护版本连接 Claude 和 FreeCAD 的桥梁从 GitHub 克隆关键检查点 1Python 版本FreeCAD 内置了一个 Python 解释器。最稳妥的方式是使用 FreeCAD 自带的 Python来运行 MCP 服务器。你可以通过以下方式找到它WindowsFreeCAD 安装目录下通常有一个bin或Python文件夹里面的python.exe或python3.exe就是。macOS/LinuxFreeCAD 的应用程序包内包含 Python路径可能较深。也可以通过终端命令which freecad找到 FreeCAD 主程序其同级目录下可能有 Python。打开系统终端或 FreeCAD 内部的 Python 控制台输入python --version或python3 --version记下版本号例如Python 3.8.10。后续步骤将依赖此版本。关键检查点 2FreeCAD 的 Python 环境确保 FreeCAD 的 Python 可以正常导入FreeCAD和Draft等模块。打开终端使用 FreeCAD 的 Python 路径执行# 将 /path/to/freecad/python 替换为你的实际路径 /path/to/freecad/python -c “import FreeCAD; import Draft; print(‘FreeCAD import successful’)”如果成功打印信息说明环境基本正常。2.2 获取 FreeCAD MCP 服务器代码目前Anthropic 官方并未提供官方的 FreeCAD MCP 服务器。我们需要使用社区开发者维护的版本。一个可靠的选择是codelv/freecad-mcp仓库。打开终端Windows 用户可使用 Git Bash 或 PowerShell。导航到一个你打算存放代码的目录例如~/Projects。执行克隆命令git clone https://github.com/codelv/freecad-mcp.git cd freecad-mcp查看README.md文件了解最新的安装要求和注意事项。2.3 理解两种连接方式Stdio 与 HTTPMCP 服务器可以通过两种方式与 Claude Desktop 通信你需要根据实际情况选择一种Stdio标准输入输出最简单的方式。Claude Desktop 直接启动 MCP 服务器进程并通过管道进行通信。优点是配置简单无需网络。缺点是如果服务器脚本崩溃需要手动重启。HTTPMCP 服务器作为一个常驻的 HTTP 服务运行。Claude Desktop 通过网络请求与之通信。优点是服务稳定可远程连接需配置安全策略便于调试。缺点是配置稍复杂涉及端口和可能的跨域问题。对于初次尝试强烈建议使用 Stdio 方式它更直接排错路径更短。本教程也将以 Stdio 方式为主线。3. 逐步配置从安装服务器到建立连接现在我们开始动手搭建。请严格按照顺序操作并在每个步骤后验证是否成功。3.1 安装 MCP 服务器依赖进入你克隆的freecad-mcp目录。通常项目会提供一个requirements.txt文件。使用 FreeCAD 的 Python 创建虚拟环境可选但推荐 虚拟环境可以隔离依赖避免污染系统 Python。# 使用 FreeCAD 的 Python 创建虚拟环境 /path/to/freecad/python -m venv venv # 激活虚拟环境 # Windows (cmd): venv\Scripts\activate # Windows (PowerShell): .\venv\Scripts\Activate.ps1 # macOS/Linux: source venv/bin/activate激活后终端提示符前会出现(venv)字样。安装依赖包pip install -r requirements.txt如果项目没有requirements.txt你可能需要手动安装核心依赖mcppip install mcp3.2 配置 Claude Desktop这是最关键的一步需要创建 Claude Desktop 的配置文件告诉它如何找到我们的 MCP 服务器。找到 Claude Desktop 的配置目录macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在请手动创建。编辑配置文件 用文本编辑器如 VS Code、Notepad打开claude_desktop_config.json文件。 写入以下配置内容请仔细阅读注释并根据你的路径修改{ “mcpServers”: { “freecad”: { “command”: “/path/to/your/freecad-mcp/venv/bin/python”, // 重要指向虚拟环境中的python “args”: [ “/path/to/your/freecad-mcp/server.py” // 重要指向服务器主脚本 ], “env”: { “FREECAD_PATH”: “/Applications/FreeCAD.app/Contents/Resources” // 重要指向FreeCAD资源目录macOS示例 // Windows 示例: “C:\\Program Files\\FreeCAD 0.21\\bin” // Linux 示例: “/usr/lib/freecad/lib” } } } }参数详解与避坑指南command必须指向你刚刚创建并安装了依赖的虚拟环境中的 Python 解释器。不要直接使用系统 Python。args指向 MCP 服务器的主 Python 脚本文件通常是server.py。env.FREECAD_PATH这是最容易出错的地方。这个环境变量需要帮助 Python 找到 FreeCAD 的库文件。macOS通常指向FreeCAD.app/Contents/Resources。Windows指向 FreeCAD 安装目录下的bin文件夹例如C:\Program Files\FreeCAD 0.21\bin。Linux指向包含FreeCAD.so等库文件的目录例如/usr/lib/freecad/lib。如何验证如果后续连接失败并出现ImportError: No module named ‘FreeCAD’就说明这个路径设置不对。你需要找到 FreeCAD 安装目录下包含FreeCAD.so(Unix) 或FreeCAD.pyd(Windows) 文件的文件夹。保存配置文件。3.3 启动与验证连接完全重启 Claude Desktop修改配置文件后必须完全退出并重新启动 Claude Desktop 应用配置才能生效。观察启动日志启动 Claude Desktop 时留意其日志窗口如果提供或系统控制台。如果配置正确你应该能看到它尝试启动freecadMCP 服务器的信息。在 FreeCAD 中打开一个文档新建或打开一个已有的.FCStd文件。确保 FreeCAD 处于运行状态。与 Claude 对话测试在 Claude Desktop 中新建一个对话。输入一条简单的 MCP 指令来测试。例如/freecad list_documents或freecad 列出所有文档具体指令格式取决于你使用的 MCP 服务器实现请参考其README.md。常见的测试指令包括list_documents或get_documents列出所有打开的 FreeCAD 文档。list_objects [文档名]列出指定文档中的所有对象。create_box [文档名] [长] [宽] [高]在指定文档中创建一个长方体。成功标志Claude 应该能回复你例如“当前打开的文档有Unnamed。” 或者它成功创建了一个长方体你可以在 FreeCAD 的视图窗口中立即看到变化。失败排查 如果 Claude 回复“无法连接到 MCP 服务器”或命令执行失败请按以下顺序检查配置文件语法JSON 格式必须正确不能有注释上述示例中的注释仅为说明实际配置文件中需删除。路径是否正确再次核对command、args和env.FREECAD_PATH的每一个路径确保无拼写错误且文件真实存在。虚拟环境确认command指向的 Python 确实在虚拟环境中并且已安装mcp等依赖。FreeCAD 路径FREECAD_PATH是最大的坑。尝试在终端中用配置的 Python 手动运行server.py看是否报导入错误。cd /path/to/your/freecad-mcp FREECAD_PATH”/your/freecad/path” /path/to/your/venv/bin/python server.py观察输出根据错误信息调整FREECAD_PATH。查看 Claude Desktop 日志在配置目录或系统标准错误输出中查找更详细的错误信息。4. 超越连接实用场景、高级配置与故障排除当基础连接建立后真正的价值才开始体现。我们来探索如何用好这个工具并解决可能遇到的进阶问题。4.1 核心使用场景与示例连接成功后Claude 就成为了 FreeCAD 的智能扩展。以下是一些实用的对话示例场景一信息查询与检查你“freecad 当前活动文档叫什么里面有哪些对象”Claude“当前活动文档是 ‘Bracket’。包含的对象有SketchPadFillet。”你“检查一下Sketch草图是否完全约束”Claude“Sketch草图共有12个约束状态为‘完全约束’。”场景二参数化建模与修改你“在 ‘Bracket’ 文档中创建一个长50mm、宽30mm、高10mm的长方体命名为 ‘BasePlate’。”Claude“已创建长方体 ‘BasePlate’。” 你会在 FreeCAD 中立即看到新对象你“将 ‘BasePlate’ 的 ‘Length’ 属性修改为 60mm。”Claude“已将 ‘BasePlate.Length’ 从 50mm 修改为 60mm。”场景三自动化重复操作你“为文档中所有 ‘Box’ 类型的对象添加一个 2mm 的圆角。”Claude“已为对象 ‘Box001’ ‘Box002’ 添加了圆角特征。”你“生成当前文档中所有零件的物料清单BOM包含名称和体积。”Claude“| 名称 | 体积 (mm³) | |---|---| | BasePlate | 18000 | | Cylinder | 785.4 |”场景四学习与调试你“我想在选中的面上创建一个钻孔用 Python 宏应该怎么写”Claude在理解当前选中面的上下文后“根据您当前选中的面对应的 Python 代码大致如下...。需要我直接为您执行吗”你“执行吧。”4.2 进阶配置使用 HTTP 服务器模式如果你希望 MCP 服务器更稳定或者想从其他客户端连接可以配置为 HTTP 模式。修改服务器启动方式通常需要修改server.py或使用额外的启动参数使其启动一个 HTTP 服务。例如社区服务器可能支持python server.py --transport http --port 8080修改 Claude Desktop 配置将command模式改为url模式。{ “mcpServers”: { “freecad”: { “url”: “http://localhost:8080” // 假设服务器运行在本地8080端口 } } }注意防火墙确保本地端口如 8080没有被防火墙阻止。安全警告HTTP 模式默认仅在本地回环地址localhost运行相对安全。切勿未经安全加固就将服务暴露在公网。4.3 常见故障与解决方案即使按照教程操作也可能遇到独特的问题。这里有一个排查清单问题现象可能原因解决方案Claude 提示“无法连接到 MCP 服务器”1. 配置文件路径错误。2. 虚拟环境 Python 路径错误。3.server.py脚本启动即崩溃。1. 检查 JSON 语法和所有路径。2. 在终端手动运行command和args指定的命令看是否有错误输出。3. 查看 Claude Desktop 的应用日志。错误ImportError: No module named ‘FreeCAD’FREECAD_PATH环境变量设置不正确Python 找不到 FreeCAD 模块。1. 确认FREECAD_PATH指向包含FreeCAD.so/FreeCAD.pyd的目录。2. 在终端中手动设置该变量后运行 Python尝试import FreeCAD进行测试。命令执行成功但 FreeCAD 中无变化1. FreeCAD 未运行或未打开目标文档。2. MCP 服务器操作的是错误的文档。3. FreeCAD GUI 未刷新。1. 确保 FreeCAD 在前台运行并有活动文档。2. 明确指定文档名进行操作。3. 尝试在 FreeCAD 中按F5刷新树视图或切换一下标签页。Claude 不认识/freecad命令MCP 服务器工具列表未正确加载或指令格式不对。1. 重启 Claude Desktop。2. 在 Claude 输入框中输入并等待看是否有freecad的自动补全提示。3. 参考服务器文档使用正确的工具调用格式。性能缓慢或操作超时1. 复杂操作本身耗时。2. Stdio 通信存在瓶颈。1. 对于复杂操作请耐心等待。2. 考虑使用 HTTP 模式或检查是否有其他进程占用资源。4.4 安全与隐私考量将 AI 连接到你的设计软件必须考虑安全本地运行本教程的配置下所有通信Claude - MCP 服务器 - FreeCAD都发生在你的本地计算机上设计数据不会上传到云端Claude 的对话内容本身仍受其隐私政策约束。权限最小化MCP 服务器拥有通过 Python API 操作 FreeCAD 的完整权限。请确保你从可信来源如知名的 GitHub 仓库获取服务器代码。网络隔离如果使用 HTTP 模式除非有特殊需求否则务必将其绑定到127.0.0.1localhost不要绑定到0.0.0.0暴露给网络。5. 从连接到创造重新思考 AI 与专业工具的工作流成功配置只是起点。这套工作流的真正价值在于它开启了一种新的可能性让 AI 从“外部顾问”转变为“嵌入式协作者”。过去我们使用 AI 辅助设计流程是割裂的思考 - 切换到浏览器/聊天工具 - 描述问题 - 等待回复 - 理解回复 - 切换回 CAD 软件 - 手动实施。中间存在多次上下文切换和格式转换的损耗。现在工作流变成了在 CAD 软件中思考 - 直接向“内置”的 AI 助手发出自然语言指令 - AI 理解当前设计上下文并直接执行操作 - 结果实时反馈在软件界面上。这是一个闭环。这意味着你可以进行探索性设计“尝试用5种不同的半径对这个边进行倒圆角并分别计算体积。”快速生成变体“基于这个齿轮草图生成模数从1到3齿数从15到25的所有组合模型。”自动化繁琐检查“检查装配体中所有间隙是否小于0.1mm。”获取即时教程“我现在选中了这个曲面教我如何用它做放样操作。” AI 不仅可以给出步骤还能直接演示。当然这并非万能。目前的 MCP 服务器实现的功能集是有限的复杂的、需要创造性判断的操作仍然离不开设计师。AI 可能会误解你的意图或生成不符合几何逻辑的操作。因此它最佳的角色定位是“超级快捷键”和“实时知识库”负责执行那些你明确知道怎么做、但操作起来很繁琐的任务或者帮你快速查询信息和验证想法。给你的最终建议是不要试图一开始就让 AI 完成整个设计。从一些小的、离散的任务开始比如查询属性、修改参数、创建标准形状。在反复的交互中你和 AI 会逐渐磨合你也能更准确地把握它的能力和边界。同时关注 MCP 社区的发展随着工具集的丰富你能自动化的事情会越来越多。技术的意义不在于替代而在于拓展。当 Claude 能够直接操作 FreeCAD 时它拓展的不是 AI 的能力而是你——设计师、工程师——的思维带宽让你能将更多精力集中于设计本身而非软件操作。现在桥梁已经架好是时候开始你的探索了。