1. 先搞清楚“Claude AI连接FreeCAD”到底能帮你做什么如果你正在用FreeCAD做设计尤其是涉及到参数化建模、脚本编写或者重复性操作可能会觉得手动调整每个参数、写每一行代码有点繁琐。这时候把Claude AI这类大语言模型接进来核心价值就出来了它能让AI帮你理解设计意图并自动生成或修改FreeCAD的Python脚本。这听起来很酷但别急着动手。这个“连接”不是像装个插件那样点一下就行。它背后依赖一个叫MCPModel Context Protocol的协议。简单说MCP就是一个让AI模型比如Claude能安全、可控地访问和使用外部工具比如FreeCAD的桥梁。所以这个教程的核心其实是教你如何在本地搭建一个MCP服务器让Claude通过这个服务器去“操作”FreeCAD。适合谁看主要分两类人FreeCAD的中高级用户你已经熟悉FreeCAD的基本操作和它的Python控制台想用自然语言描述来驱动建模提升效率。对AI应用落地的开发者/爱好者你想亲手实践如何将一个具体的桌面软件FreeCAD接入大模型了解MCP这类协议的实际部署。最值得关注的点不是功能演示而是稳定性。因为涉及本地服务、网络端口、模型权限和FreeCAD的Python环境任何一个环节配置不对整个链路就断了。我跑通后的感受是一旦配置正确它确实能让你用对话的方式生成复杂脚本但前期搭建需要一点耐心。2. 动手前的准备环境、账号与核心概念在开始敲命令之前请先确认好下面几样东西。缺了任何一样后面都会报错。2.1 硬件与基础软件环境操作系统Windows 10/11, macOS 或 Linux 均可。教程流程在原理上通用但部分安装命令和路径写法会有差异本文会以Windows为主兼顾提及其他系统的注意点。FreeCAD确保你已经安装了FreeCAD。版本最好在0.21或以上老版本可能对Python支持或某些API有差异。安装后打开FreeCAD能在菜单中找到“Python控制台”并正常使用这是基础。Python这是整个MCP服务器的运行环境。你需要安装Python版本建议3.8到3.11之间。太老的版本可能缺少依赖太新的版本如3.12可能存在某些包兼容性问题。在终端输入python --version或python3 --version确认。代码编辑器或终端你需要一个能舒适执行命令行操作的环境。Windows可以用PowerShell或CMD也可以用VS Code的集成终端。2.2 关键的“通行证”Claude API 密钥Claude AI在这里不是指你访问的网页版而是需要通过Anthropic公司提供的API来调用。这意味着你需要一个Anthropic的账号。你需要在这个账号下创建一个API Key。通常可以在Anthropic的开发者控制台找到。这个Key是付费的虽然新账号可能有免费额度但本质上它是按使用量计费的。开始实验前请了解相关计费政策。这个API Key是你本地MCP服务器与云端Claude模型对话的“门票”没有它后续步骤无法进行。2.3 理解核心组件MCP服务器与客户端这是最容易混淆的地方我们先拆开看FreeCAD MCP 服务器这是一个需要你本地运行的Python程序。它的作用是把FreeCAD的功能比如创建草图、拉伸、查询对象属性包装成一系列“工具”并暴露出来。服务器本身不包含AI模型它只是个“翻译官”和“执行者”。MCP 客户端这是真正与Claude AI对话的部分。客户端会加载你配置的MCP服务器即FreeCAD工具集然后将你的自然语言指令和服务器提供的工具描述一起发送给Claude API。Claude思考后会告诉客户端“应该调用哪个工具、传入什么参数”。客户端再把这个调用请求发给本地服务器执行。Claude AI云端它负责理解你的意图并规划出调用工具的正确顺序和参数。它不直接操作你的电脑所有实际操作都在你本地的MCP服务器上完成。所以流程是你 - MCP客户端 - Claude API云端- MCP客户端 - FreeCAD MCP服务器本地- FreeCAD。搭建过程主要就是在配置这个本地服务器和客户端。3. 逐步搭建从零部署FreeCAD MCP服务器这里我们假设你使用一个常见的MCP客户端框架比如mcp-cli或通过Claude Desktop App配置。由于Claude Desktop的集成相对直观我们以其为例但原理相通。3.1 第一步创建并配置MCP服务器项目首先为你本地服务器创建一个独立的工作目录避免环境混乱。mkdir freecad-mcp-server cd freecad-mcp-server接下来创建一个Python虚拟环境。这是强烈推荐的做法可以隔离依赖包。# Windows python -m venv venv .\venv\Scripts\activate # macOS/Linux python3 -m venv venv source venv/bin/activate激活后你的命令行提示符前会出现(venv)字样。然后安装核心依赖。最关键的是一个叫mcp的Python库以及FreeCAD的Python绑定。pip install mcp注意FreeCAD通常自带Python但你系统安装的Python可能没有。这里有个关键点MCP服务器需要能import FreeCAD和import Draft等模块。最可靠的方法是直接使用FreeCAD自带的Python解释器。找到你的FreeCAD安装目录里面会有一个bin或MacOS文件夹包含python可执行文件。例如在Windows上路径可能像C:\Program Files\FreeCAD 0.21\bin\python.exe。你可以用这个Python来创建虚拟环境和运行服务器确保环境一致。3.2 第二步编写服务器脚本server.py在freecad-mcp-server目录下创建一个server.py文件。这个文件定义了服务器向客户端提供了哪些“工具”。#!/usr/bin/env python3 import sys import os # 关键确保FreeCAD的Python模块路径被加入 sys.path.append(rC:\Program Files\FreeCAD 0.21\bin) # Windows示例请修改为你的路径 sys.path.append(rC:\Program Files\FreeCAD 0.21\lib) # Windows示例请修改为你的路径 from mcp.server import Server import mcp.server.stdio import FreeCAD import Draft import Part # 初始化FreeCAD文档后台运行不显示GUI FreeCAD.newDocument(Unnamed) app Server(freecad-server) # 定义工具创建一个立方体 app.list_tools() async def handle_list_tools(): return [ { name: create_box, description: 在FreeCAD中创建一个立方体。, inputSchema: { type: object, properties: { length: {type: number, description: 立方体长度mm}, width: {type: number, description: 立方体宽度mm}, height: {type: number, description: 立方体高度mm}, }, required: [length, width, height] } }, { name: create_cylinder, description: 在FreeCAD中创建一个圆柱体。, inputSchema: { type: object, properties: { radius: {type: number, description: 圆柱体半径mm}, height: {type: number, description: 圆柱体高度mm}, }, required: [radius, height] } }, ] # 实现工具处理创建立方体的调用 app.call_tool() async def handle_call_tool(name: str, arguments: dict): if name create_box: length arguments[length] width arguments[width] height arguments[height] # 调用FreeCAD API创建立方体 box Part.makeBox(length, width, height) box_obj FreeCAD.ActiveDocument.addObject(Part::Feature, Box) box_obj.Shape box FreeCAD.ActiveDocument.recompute() return f已创建立方体长{length}mm宽{width}mm高{height}mm。 elif name create_cylinder: radius arguments[radius] height arguments[height] cylinder Part.makeCylinder(radius, height) cyl_obj FreeCAD.ActiveDocument.addObject(Part::Feature, Cylinder) cyl_obj.Shape cylinder FreeCAD.ActiveDocument.recompute() return f已创建圆柱体半径{radius}mm高{height}mm。 else: raise ValueError(f未知工具: {name}) if __name__ __main__: # 使用标准输入输出与客户端通信 mcp.server.stdio.run(app)代码关键点解释sys.path.append: 这行必须修改为你本地FreeCAD的实际安装路径否则会报错No module named FreeCAD。FreeCAD.newDocument: 服务器启动时自动创建一个新文档用于后续操作。app.list_tools: 这个函数告诉客户端本服务器提供了哪些工具这里示例是create_box和create_cylinder以及每个工具需要什么参数。app.call_tool: 这是工具的实际执行函数。当客户端发来指令时它根据工具名和参数调用真正的FreeCAD APIPart.makeBox,Part.makeCylinder来创建几何体。mcp.server.stdio.run(app): 让服务器以标准输入输出模式运行这是与MCP客户端通信的常用方式。注意这是一个极简示例只实现了两个基础功能。真正的生产级服务器会包含更多工具如草图绘制、约束添加、模型查询、导出文件等代码结构也会更复杂需要错误处理。但作为入门先用这两个工具跑通整个链路最重要。3.3 第三步配置Claude Desktop连接MCP服务器如果你使用Claude Desktop App这是Anthropic官方的桌面客户端支持配置MCP配置相对简单。找到Claude Desktop的配置文件夹。Windows:%APPDATA%\Claude\macOS:~/Library/Application Support/Claude/Linux:~/.config/Claude/在该文件夹下创建或编辑一个名为claude_desktop_config.json的文件。在配置文件中添加你的MCP服务器配置。内容大致如下{ mcpServers: { freecad: { command: C:\\Users\\你的用户名\\freecad-mcp-server\\venv\\Scripts\\python.exe, args: [C:\\Users\\你的用户名\\freecad-mcp-server\\server.py], env: { PYTHONPATH: C:\\Program Files\\FreeCAD 0.21\\bin;C:\\Program Files\\FreeCAD 0.21\\lib } } } }配置参数解析command: 这里必须指向你虚拟环境中的python解释器的完整路径确保它安装了mcp库。args: 参数列表第一个就是你写的server.py的完整路径。env: 环境变量。这里设置了PYTHONPATH再次确保Python能找到FreeCAD的模块。路径以分号分隔WindowsmacOS/Linux用冒号。保存配置文件然后完全重启Claude Desktop App。3.4 第四步验证与首次对话重启Claude Desktop后理论上它会在后台自动启动你配置的MCP服务器。打开Claude Desktop新建一个对话。你应该能在输入框附近或设置里看到已连接的“工具”或“服务器”标识。不同版本UI可能不同。尝试发送指令。指令需要清晰并符合你定义的工具描述。例如“请使用FreeCAD工具创建一个长50mm、宽30mm、高20mm的立方体。”“帮我画一个半径10mm高40mm的圆柱体。”如果配置成功Claude会理解你的指令识别出需要调用create_box或create_cylinder工具并生成相应的参数。然后客户端会将调用请求发送给你的本地server.py脚本执行在FreeCAD后台文档中创建对应的几何体。如何验证成功了不要期待在Claude的聊天窗口里看到3D模型。正确的验证方式是打开FreeCAD桌面程序。你应该能看到一个名为“Unnamed”的文档由服务器脚本创建。在左侧的“模型”树状图中应该能看到新出现的“Box”或“Cylinder”对象。或者在FreeCAD的Python控制台中运行FreeCAD.ActiveDocument.Objects查看对象列表。4. 深入排查当连接失败或指令无效时大概率你第一次不会那么顺利。下面是我踩过坑后整理的排查清单按顺序检查4.1 现象Claude完全“看不到”FreeCAD工具检查点1Claude Desktop配置是否正确确认claude_desktop_config.json文件在正确的位置且格式是合法的JSON可以用在线JSON校验工具检查。确认配置中的command和args路径完全正确尤其是Windows的路径反斜杠需要转义\\。重启Claude Desktop。任何配置修改后必须重启客户端才能生效。检查点2MCP服务器是否成功启动打开系统任务管理器查看是否有python.exe进程在运行且命令行参数包含你的server.py。你可以手动在终端运行你的服务器脚本看是否有报错cd C:\你的路径\freecad-mcp-server .\venv\Scripts\activate python server.py如果手动运行都报错如ModuleNotFoundError: No module named FreeCAD那问题就在服务器脚本本身。重点检查sys.path.append的路径。检查点3FreeCAD的Python环境这是最常见的坑。确保你的server.py使用的Python解释器能够导入FreeCAD模块。一个测试方法是用你配置中指定的Python虚拟环境里的手动进入Python交互模式尝试import FreeCAD和import Part。如果失败说明PYTHONPATH环境变量或sys.path设置不对。4.2 现象Claude能看到工具但调用后FreeCAD没反应检查点1FreeCAD文档是否已创建你的server.py里调用了FreeCAD.newDocument(Unnamed)。确保FreeCAD桌面程序打开时这个文档存在。有时服务器可能在另一个FreeCAD实例中创建文档而你看的是另一个窗口。检查点2工具参数传递是否正确在server.py的handle_call_tool函数里可以添加简单的打印语句例如print(f“调用工具 {name}参数 {arguments}”)这样在服务器运行的终端如果你手动运行就能看到是否收到了请求。确保Claude生成的参数格式完全符合你定义的inputSchema。例如length应该是数字不是字符串。检查点3FreeCAD API调用是否成功FreeCAD的某些操作需要在“编辑”模式下或者需要主动重算文档recompute()。示例代码中已经包含了recompute()。查看FreeCAD的“报告视图”或“Python控制台”是否有红色错误信息。4.3 现象一切正常但想扩展更多功能现在你只是创建了基本几何体。要真正有用你需要扩展server.py。添加更多工具在handle_list_tools返回的列表里增加新工具定义如create_sketch,extrude,fillet_edge,export_stl等。实现工具函数在handle_call_tool里增加对应的elif分支调用更丰富的FreeCAD API。错误处理在工具函数中加入try...except将FreeCAD可能抛出的异常捕获并返回友好信息给客户端。状态管理当前的简单示例每次操作都是独立的。更复杂的操作可能需要服务器维护一些状态比如当前选中的对象是哪个。这需要更复杂的设计。5. 生产级考量与安全边界把实验玩起来和真正用于工作是两回事。如果你打算深入使用必须考虑以下几点5.1 性能与稳定性资源占用同时运行FreeCAD即使是后台、MCP服务器、Claude Desktop和可能的浏览器对内存有一定要求。处理复杂模型时更甚。响应延迟指令从发出到FreeCAD执行完成链条较长涉及网络请求到Claude API和本地进程通信不适合对实时性要求极高的操作。错误恢复如果MCP服务器进程意外崩溃Claude Desktop的连接会中断。需要手动重启服务器。在生产部署中需要考虑进程守护和自动重启。5.2 安全与权限API密钥保护你的Claude API Key是写在Claude Desktop配置里的确保不要泄露。不要将包含密钥的配置文件上传到公开仓库。服务器工具权限你定义的MCP工具拥有执行它代码的权限。这意味着如果你定义了一个delete_all_documents工具Claude就有可能调用它。务必仔细设计和审查暴露给AI的工具集避免提供危险操作。本地文件访问如果工具涉及读取或写入本地文件要警惕路径遍历等安全风险确保AI操作的文件范围是受控的。5.3 替代方案与进阶方向使用其他MCP客户端除了Claude Desktop你也可以用mcp-cli命令行工具或者自己写一个简单的客户端脚本这样更灵活可以集成到其他自动化流程中。连接其他AI模型MCP是开放协议。理论上你可以将同一个FreeCAD MCP服务器配置给其他支持MCP的AI客户端使用比如某些开源的AI助手框架。从“生成脚本”到“直接操作”目前的模式是“AI规划 - 调用工具 - 执行单一API”。更高级的模式是AI直接生成一段完整的、可执行的FreeCAD Python脚本然后服务器一次性执行。这给了AI更大的灵活性但也对AI的代码生成能力和错误处理提出了更高要求。我个人更建议在初期不要把目标定得太大。先像本教程一样用一两个最简单的工具创建立方体、圆柱体把整个“提问 - AI理解 - 调用 - FreeCAD执行”的闭环跑通。这个闭环通了你就能深刻理解每个环节的作用和可能的问题。之后再根据你的实际工作流逐个添加真正有用的工具比如“在两个点之间连线”、“给这个边倒圆角”、“计算这个实体的体积”这样积累起来的系统才最贴合你的需求也最稳定。记住AI在这里的角色是“高级脚本生成助手”它不能替代你对FreeCAD本身操作和Python API的理解。你对FreeCAD越熟就能设计出越精准、越有用的工具这个连接的价值也就越大。
1. 先搞清楚“Claude AI连接FreeCAD”到底能帮你做什么如果你正在用FreeCAD做设计尤其是涉及到参数化建模、脚本编写或者重复性操作可能会觉得手动调整每个参数、写每一行代码有点繁琐。这时候把Claude AI这类大语言模型接进来核心价值就出来了它能让AI帮你理解设计意图并自动生成或修改FreeCAD的Python脚本。这听起来很酷但别急着动手。这个“连接”不是像装个插件那样点一下就行。它背后依赖一个叫MCPModel Context Protocol的协议。简单说MCP就是一个让AI模型比如Claude能安全、可控地访问和使用外部工具比如FreeCAD的桥梁。所以这个教程的核心其实是教你如何在本地搭建一个MCP服务器让Claude通过这个服务器去“操作”FreeCAD。适合谁看主要分两类人FreeCAD的中高级用户你已经熟悉FreeCAD的基本操作和它的Python控制台想用自然语言描述来驱动建模提升效率。对AI应用落地的开发者/爱好者你想亲手实践如何将一个具体的桌面软件FreeCAD接入大模型了解MCP这类协议的实际部署。最值得关注的点不是功能演示而是稳定性。因为涉及本地服务、网络端口、模型权限和FreeCAD的Python环境任何一个环节配置不对整个链路就断了。我跑通后的感受是一旦配置正确它确实能让你用对话的方式生成复杂脚本但前期搭建需要一点耐心。2. 动手前的准备环境、账号与核心概念在开始敲命令之前请先确认好下面几样东西。缺了任何一样后面都会报错。2.1 硬件与基础软件环境操作系统Windows 10/11, macOS 或 Linux 均可。教程流程在原理上通用但部分安装命令和路径写法会有差异本文会以Windows为主兼顾提及其他系统的注意点。FreeCAD确保你已经安装了FreeCAD。版本最好在0.21或以上老版本可能对Python支持或某些API有差异。安装后打开FreeCAD能在菜单中找到“Python控制台”并正常使用这是基础。Python这是整个MCP服务器的运行环境。你需要安装Python版本建议3.8到3.11之间。太老的版本可能缺少依赖太新的版本如3.12可能存在某些包兼容性问题。在终端输入python --version或python3 --version确认。代码编辑器或终端你需要一个能舒适执行命令行操作的环境。Windows可以用PowerShell或CMD也可以用VS Code的集成终端。2.2 关键的“通行证”Claude API 密钥Claude AI在这里不是指你访问的网页版而是需要通过Anthropic公司提供的API来调用。这意味着你需要一个Anthropic的账号。你需要在这个账号下创建一个API Key。通常可以在Anthropic的开发者控制台找到。这个Key是付费的虽然新账号可能有免费额度但本质上它是按使用量计费的。开始实验前请了解相关计费政策。这个API Key是你本地MCP服务器与云端Claude模型对话的“门票”没有它后续步骤无法进行。2.3 理解核心组件MCP服务器与客户端这是最容易混淆的地方我们先拆开看FreeCAD MCP 服务器这是一个需要你本地运行的Python程序。它的作用是把FreeCAD的功能比如创建草图、拉伸、查询对象属性包装成一系列“工具”并暴露出来。服务器本身不包含AI模型它只是个“翻译官”和“执行者”。MCP 客户端这是真正与Claude AI对话的部分。客户端会加载你配置的MCP服务器即FreeCAD工具集然后将你的自然语言指令和服务器提供的工具描述一起发送给Claude API。Claude思考后会告诉客户端“应该调用哪个工具、传入什么参数”。客户端再把这个调用请求发给本地服务器执行。Claude AI云端它负责理解你的意图并规划出调用工具的正确顺序和参数。它不直接操作你的电脑所有实际操作都在你本地的MCP服务器上完成。所以流程是你 - MCP客户端 - Claude API云端- MCP客户端 - FreeCAD MCP服务器本地- FreeCAD。搭建过程主要就是在配置这个本地服务器和客户端。3. 逐步搭建从零部署FreeCAD MCP服务器这里我们假设你使用一个常见的MCP客户端框架比如mcp-cli或通过Claude Desktop App配置。由于Claude Desktop的集成相对直观我们以其为例但原理相通。3.1 第一步创建并配置MCP服务器项目首先为你本地服务器创建一个独立的工作目录避免环境混乱。mkdir freecad-mcp-server cd freecad-mcp-server接下来创建一个Python虚拟环境。这是强烈推荐的做法可以隔离依赖包。# Windows python -m venv venv .\venv\Scripts\activate # macOS/Linux python3 -m venv venv source venv/bin/activate激活后你的命令行提示符前会出现(venv)字样。然后安装核心依赖。最关键的是一个叫mcp的Python库以及FreeCAD的Python绑定。pip install mcp注意FreeCAD通常自带Python但你系统安装的Python可能没有。这里有个关键点MCP服务器需要能import FreeCAD和import Draft等模块。最可靠的方法是直接使用FreeCAD自带的Python解释器。找到你的FreeCAD安装目录里面会有一个bin或MacOS文件夹包含python可执行文件。例如在Windows上路径可能像C:\Program Files\FreeCAD 0.21\bin\python.exe。你可以用这个Python来创建虚拟环境和运行服务器确保环境一致。3.2 第二步编写服务器脚本server.py在freecad-mcp-server目录下创建一个server.py文件。这个文件定义了服务器向客户端提供了哪些“工具”。#!/usr/bin/env python3 import sys import os # 关键确保FreeCAD的Python模块路径被加入 sys.path.append(rC:\Program Files\FreeCAD 0.21\bin) # Windows示例请修改为你的路径 sys.path.append(rC:\Program Files\FreeCAD 0.21\lib) # Windows示例请修改为你的路径 from mcp.server import Server import mcp.server.stdio import FreeCAD import Draft import Part # 初始化FreeCAD文档后台运行不显示GUI FreeCAD.newDocument(Unnamed) app Server(freecad-server) # 定义工具创建一个立方体 app.list_tools() async def handle_list_tools(): return [ { name: create_box, description: 在FreeCAD中创建一个立方体。, inputSchema: { type: object, properties: { length: {type: number, description: 立方体长度mm}, width: {type: number, description: 立方体宽度mm}, height: {type: number, description: 立方体高度mm}, }, required: [length, width, height] } }, { name: create_cylinder, description: 在FreeCAD中创建一个圆柱体。, inputSchema: { type: object, properties: { radius: {type: number, description: 圆柱体半径mm}, height: {type: number, description: 圆柱体高度mm}, }, required: [radius, height] } }, ] # 实现工具处理创建立方体的调用 app.call_tool() async def handle_call_tool(name: str, arguments: dict): if name create_box: length arguments[length] width arguments[width] height arguments[height] # 调用FreeCAD API创建立方体 box Part.makeBox(length, width, height) box_obj FreeCAD.ActiveDocument.addObject(Part::Feature, Box) box_obj.Shape box FreeCAD.ActiveDocument.recompute() return f已创建立方体长{length}mm宽{width}mm高{height}mm。 elif name create_cylinder: radius arguments[radius] height arguments[height] cylinder Part.makeCylinder(radius, height) cyl_obj FreeCAD.ActiveDocument.addObject(Part::Feature, Cylinder) cyl_obj.Shape cylinder FreeCAD.ActiveDocument.recompute() return f已创建圆柱体半径{radius}mm高{height}mm。 else: raise ValueError(f未知工具: {name}) if __name__ __main__: # 使用标准输入输出与客户端通信 mcp.server.stdio.run(app)代码关键点解释sys.path.append: 这行必须修改为你本地FreeCAD的实际安装路径否则会报错No module named FreeCAD。FreeCAD.newDocument: 服务器启动时自动创建一个新文档用于后续操作。app.list_tools: 这个函数告诉客户端本服务器提供了哪些工具这里示例是create_box和create_cylinder以及每个工具需要什么参数。app.call_tool: 这是工具的实际执行函数。当客户端发来指令时它根据工具名和参数调用真正的FreeCAD APIPart.makeBox,Part.makeCylinder来创建几何体。mcp.server.stdio.run(app): 让服务器以标准输入输出模式运行这是与MCP客户端通信的常用方式。注意这是一个极简示例只实现了两个基础功能。真正的生产级服务器会包含更多工具如草图绘制、约束添加、模型查询、导出文件等代码结构也会更复杂需要错误处理。但作为入门先用这两个工具跑通整个链路最重要。3.3 第三步配置Claude Desktop连接MCP服务器如果你使用Claude Desktop App这是Anthropic官方的桌面客户端支持配置MCP配置相对简单。找到Claude Desktop的配置文件夹。Windows:%APPDATA%\Claude\macOS:~/Library/Application Support/Claude/Linux:~/.config/Claude/在该文件夹下创建或编辑一个名为claude_desktop_config.json的文件。在配置文件中添加你的MCP服务器配置。内容大致如下{ mcpServers: { freecad: { command: C:\\Users\\你的用户名\\freecad-mcp-server\\venv\\Scripts\\python.exe, args: [C:\\Users\\你的用户名\\freecad-mcp-server\\server.py], env: { PYTHONPATH: C:\\Program Files\\FreeCAD 0.21\\bin;C:\\Program Files\\FreeCAD 0.21\\lib } } } }配置参数解析command: 这里必须指向你虚拟环境中的python解释器的完整路径确保它安装了mcp库。args: 参数列表第一个就是你写的server.py的完整路径。env: 环境变量。这里设置了PYTHONPATH再次确保Python能找到FreeCAD的模块。路径以分号分隔WindowsmacOS/Linux用冒号。保存配置文件然后完全重启Claude Desktop App。3.4 第四步验证与首次对话重启Claude Desktop后理论上它会在后台自动启动你配置的MCP服务器。打开Claude Desktop新建一个对话。你应该能在输入框附近或设置里看到已连接的“工具”或“服务器”标识。不同版本UI可能不同。尝试发送指令。指令需要清晰并符合你定义的工具描述。例如“请使用FreeCAD工具创建一个长50mm、宽30mm、高20mm的立方体。”“帮我画一个半径10mm高40mm的圆柱体。”如果配置成功Claude会理解你的指令识别出需要调用create_box或create_cylinder工具并生成相应的参数。然后客户端会将调用请求发送给你的本地server.py脚本执行在FreeCAD后台文档中创建对应的几何体。如何验证成功了不要期待在Claude的聊天窗口里看到3D模型。正确的验证方式是打开FreeCAD桌面程序。你应该能看到一个名为“Unnamed”的文档由服务器脚本创建。在左侧的“模型”树状图中应该能看到新出现的“Box”或“Cylinder”对象。或者在FreeCAD的Python控制台中运行FreeCAD.ActiveDocument.Objects查看对象列表。4. 深入排查当连接失败或指令无效时大概率你第一次不会那么顺利。下面是我踩过坑后整理的排查清单按顺序检查4.1 现象Claude完全“看不到”FreeCAD工具检查点1Claude Desktop配置是否正确确认claude_desktop_config.json文件在正确的位置且格式是合法的JSON可以用在线JSON校验工具检查。确认配置中的command和args路径完全正确尤其是Windows的路径反斜杠需要转义\\。重启Claude Desktop。任何配置修改后必须重启客户端才能生效。检查点2MCP服务器是否成功启动打开系统任务管理器查看是否有python.exe进程在运行且命令行参数包含你的server.py。你可以手动在终端运行你的服务器脚本看是否有报错cd C:\你的路径\freecad-mcp-server .\venv\Scripts\activate python server.py如果手动运行都报错如ModuleNotFoundError: No module named FreeCAD那问题就在服务器脚本本身。重点检查sys.path.append的路径。检查点3FreeCAD的Python环境这是最常见的坑。确保你的server.py使用的Python解释器能够导入FreeCAD模块。一个测试方法是用你配置中指定的Python虚拟环境里的手动进入Python交互模式尝试import FreeCAD和import Part。如果失败说明PYTHONPATH环境变量或sys.path设置不对。4.2 现象Claude能看到工具但调用后FreeCAD没反应检查点1FreeCAD文档是否已创建你的server.py里调用了FreeCAD.newDocument(Unnamed)。确保FreeCAD桌面程序打开时这个文档存在。有时服务器可能在另一个FreeCAD实例中创建文档而你看的是另一个窗口。检查点2工具参数传递是否正确在server.py的handle_call_tool函数里可以添加简单的打印语句例如print(f“调用工具 {name}参数 {arguments}”)这样在服务器运行的终端如果你手动运行就能看到是否收到了请求。确保Claude生成的参数格式完全符合你定义的inputSchema。例如length应该是数字不是字符串。检查点3FreeCAD API调用是否成功FreeCAD的某些操作需要在“编辑”模式下或者需要主动重算文档recompute()。示例代码中已经包含了recompute()。查看FreeCAD的“报告视图”或“Python控制台”是否有红色错误信息。4.3 现象一切正常但想扩展更多功能现在你只是创建了基本几何体。要真正有用你需要扩展server.py。添加更多工具在handle_list_tools返回的列表里增加新工具定义如create_sketch,extrude,fillet_edge,export_stl等。实现工具函数在handle_call_tool里增加对应的elif分支调用更丰富的FreeCAD API。错误处理在工具函数中加入try...except将FreeCAD可能抛出的异常捕获并返回友好信息给客户端。状态管理当前的简单示例每次操作都是独立的。更复杂的操作可能需要服务器维护一些状态比如当前选中的对象是哪个。这需要更复杂的设计。5. 生产级考量与安全边界把实验玩起来和真正用于工作是两回事。如果你打算深入使用必须考虑以下几点5.1 性能与稳定性资源占用同时运行FreeCAD即使是后台、MCP服务器、Claude Desktop和可能的浏览器对内存有一定要求。处理复杂模型时更甚。响应延迟指令从发出到FreeCAD执行完成链条较长涉及网络请求到Claude API和本地进程通信不适合对实时性要求极高的操作。错误恢复如果MCP服务器进程意外崩溃Claude Desktop的连接会中断。需要手动重启服务器。在生产部署中需要考虑进程守护和自动重启。5.2 安全与权限API密钥保护你的Claude API Key是写在Claude Desktop配置里的确保不要泄露。不要将包含密钥的配置文件上传到公开仓库。服务器工具权限你定义的MCP工具拥有执行它代码的权限。这意味着如果你定义了一个delete_all_documents工具Claude就有可能调用它。务必仔细设计和审查暴露给AI的工具集避免提供危险操作。本地文件访问如果工具涉及读取或写入本地文件要警惕路径遍历等安全风险确保AI操作的文件范围是受控的。5.3 替代方案与进阶方向使用其他MCP客户端除了Claude Desktop你也可以用mcp-cli命令行工具或者自己写一个简单的客户端脚本这样更灵活可以集成到其他自动化流程中。连接其他AI模型MCP是开放协议。理论上你可以将同一个FreeCAD MCP服务器配置给其他支持MCP的AI客户端使用比如某些开源的AI助手框架。从“生成脚本”到“直接操作”目前的模式是“AI规划 - 调用工具 - 执行单一API”。更高级的模式是AI直接生成一段完整的、可执行的FreeCAD Python脚本然后服务器一次性执行。这给了AI更大的灵活性但也对AI的代码生成能力和错误处理提出了更高要求。我个人更建议在初期不要把目标定得太大。先像本教程一样用一两个最简单的工具创建立方体、圆柱体把整个“提问 - AI理解 - 调用 - FreeCAD执行”的闭环跑通。这个闭环通了你就能深刻理解每个环节的作用和可能的问题。之后再根据你的实际工作流逐个添加真正有用的工具比如“在两个点之间连线”、“给这个边倒圆角”、“计算这个实体的体积”这样积累起来的系统才最贴合你的需求也最稳定。记住AI在这里的角色是“高级脚本生成助手”它不能替代你对FreeCAD本身操作和Python API的理解。你对FreeCAD越熟就能设计出越精准、越有用的工具这个连接的价值也就越大。
![【Bug已解决】[modular] ensure branch-specific input defaults 解决方案](http://pic.xiahunao.cn/yaotu/【Bug已解决】[modular] ensure branch-specific input defaults 解决方案)
