FreeCAD MCP 插件

FreeCAD MCP 插件将模型控制协议 (MCP) 集成到 FreeCAD 中，通过服务器-客户端架构实现模型创建、宏执行和视图管理的自动化。它提供了一个图形用户界面控制面板和一个命令行客户端来简化 FreeCAD 工作流程，支持诸如创建/运行宏、调整视图以及与外部工具（如 Claude、Cursor、Trace、CodeBuddy）集成的任务。

目录

• 特性
• 快速开始
• 安装
• MCP 配置
• 使用方法
• 工具功能
• 用例
• 外部工具集成
• 资源
• 故障排除
• 贡献
• 许可证

特性

FreeCAD MCP 插件（v0.1.0）提供了以下功能：

• MCP 服务器：提供一个图形用户界面控制面板（FreeCADMCPPanel），处理如 create_macro、update_macro、run_macro、set_view 和 get_report 等命令（在 freecad_mcp_server.py 中实现）。
• MCP 客户端：命令行工具通过 stdio 或 TCP 发送命令，管理 .FCMacro 文件（创建、更新、运行、验证），并远程控制 FreeCAD（在 freecad_mcp_client.py 中实现）。
• 宏规范化：自动添加导入（FreeCAD、FreeCADGui、Part、math）和后执行步骤（重新计算、调整视图）给宏。
• 图形用户界面控制面板：包括启动/停止服务器、清除日志和切换视图（前面、顶部、右侧、轴测图）的按钮。
• 日志系统：记录消息和错误到临时目录中的 freecad_mcp_log.txt（例如，%TEMP%\freecad_mcp_log.txt）和图形用户界面报告浏览器（限制100行）。
• 工作台集成：添加一个带有工具栏和菜单命令的 FreeCADMCPWorkbench（在 InitGui.py 中实现）。
• 视觉资产：包括工作台图标（icon.svg）、示例模型（gear.png、flange.png、boat.png、table.png）和演示动画（freecad.gif、freecad.mp4）。

观看演示动画： <img src="https://raw.githubusercontent.com/ATOI-Ming/FreeCAD-MCP/main/assets/freecad.gif" width="900"> 下载演示视频：FreeCAD MCP 演示 MP4

快速开始

1. 安装插件（参见安装）。
2. 启动 FreeCAD 并切换到 FreeCAD MCP 工作台。
3. 打开控制面板（FreeCAD_MCP_Show）并点击“启动服务器”。
4. 运行示例宏：

   python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 15}'
   

5. 查看结果：生成并显示一个齿轮模型，以轴测图视图展示。

安装

先决条件

• FreeCAD：版本 0.21 或更高，下载 FreeCAD。选择适合您操作系统的版本。
• Python：版本 3.12+（随 FreeCAD 提供或通过 Anaconda 安装）。
• Anaconda（推荐用于依赖项管理）：下载 Anaconda。选择适合您操作系统的版本。
• Python 依赖项：
  • 必需的包：mcp-server>=1.2.0，httpx>=0.24.1（在 pyproject.toml 中指定）。
  • 安装命令：

    # 创建并激活 Anaconda 环境
    conda create -n freecad_mcp python=3.12
    conda activate freecad_mcp
    pip install mcp-server>=1.2.0 httpx>=0.24.1
    # 或使用系统 Python
    python -m pip install mcp-server>=1.2.0 httpx>=0.24.1
    

  • 验证安装：

    pip show mcp-server httpx
    

    确保 mcp-server 版本 >=1.2.0 和 httpx 版本 >=0.24.1。

安装步骤

1. 克隆仓库：

   git clone https://github.com/ATOI-Ming/FreeCAD-MCP.git
   

2. 复制到 FreeCAD 模块目录： 将 FreeCAD-MCP 文件夹复制到：

   • Windows：D:\FreeCAD\Mod\FreeCAD-MCP
   • Linux：~/.local/share/FreeCAD/Mod/FreeCAD-MCP
   • macOS：~/Library/Application Support/FreeCAD/Mod/FreeCAD-MCP

   # Windows 示例
   xcopy FreeCAD-MCP D:\FreeCAD\Mod\FreeCAD-MCP /E /H /C /I
   

   注意：根据您的 FreeCAD 安装路径调整 D:\FreeCAD\Mod。

3. 启动 FreeCAD：

   • 打开 FreeCAD 并切换到 FreeCAD MCP 工作台（图标：assets/icon.svg）。
   • 在 编辑 > 偏好设置 > 插件 中验证 FreeCAD-MCP 是否已加载。

4. 验证安装：

   • 点击 FreeCAD_MCP_Show 打开控制面板。
   • 检查临时目录（例如，%TEMP%\freecad_mcp_log.txt）中的启动消息。

MCP 配置

配置 MCP 客户端通过 stdio 或 TCP 与 FreeCAD 通信。

1. 创建配置文件： 在 D:\FreeCAD\Mod\FreeCAD-MCP-main\src\ 创建 mcp_config.json：

   {
       "mcpServers": {
           "freecad": {
               "disabled": false,
               "timeout": 60,
               "type": "stdio",
               "command": "D:\\Anaconda3\\python.exe",
               "args": ["D:\\FreeCAD\\Mod\\FreeCAD-MCP-main\\src\\freecad_mcp_client.py"]
           }
       }
   }
   

   注意：

   • 根据您的系统调整路径：
     • Anaconda 路径：例如，C:\Anaconda3\python.exe（Windows），/home/<user>/anaconda3/bin/python（Linux），/Users/<user>/anaconda3/bin/python（macOS）。
     • FreeCAD 模块路径：例如，C:\Users\<YourUser>\AppData\Roaming\FreeCAD\Mod\FreeCAD-MCP（Windows），/home/<user>/.local/share/FreeCAD/Mod/FreeCAD-MCP（Linux），/Users/<user>/Library/Application Support/FreeCAD/Mod/FreeCAD-MCP（macOS）。
   • 对于 TCP 通信，设置 "type": "tcp"，添加 "host": "localhost" 和 "port": 9876。

2. 运行服务器：

   • 图形用户界面方法：在 FreeCAD MCP 工作台中，点击 FreeCAD_MCP_Show，然后点击“启动服务器”。
   • 命令行方法：

     conda activate freecad_mcp
     python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_server.py
     

3. 验证服务器：

   • 检查 %TEMP%\freecad_mcp_log.txt 中是否有“服务器已启动”的消息。
   • 测试客户端命令：

     python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report
     

使用方法

图形用户界面使用

1. 在 FreeCAD 中切换到 FreeCAD MCP 工作台（图标：assets/icon.svg）。
2. 点击 FreeCAD_MCP_Show 打开控制面板（FreeCADMCPPanel）。
3. 使用控制面板：
   • 启动/停止服务器：控制 MCP 服务器。
   • 清除日志：清除报告浏览器和 %TEMP%\freecad_mcp_log.txt。
   • 切换视图：选择前面、顶部、右侧或轴测图视图。
4. 运行宏：
   • 点击 FreeCAD_MCP_RunMacro，选择一个 .FCMacro 文件，并执行它，自动进行规范化。

命令行使用

1. 激活 Anaconda 环境：

   conda activate freecad_mcp
   

2. 运行客户端命令：

   python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py <command>
   

   示例：
   • 创建宏：--create-macro my_macro --template-type part
   • 运行宏：--run-macro my_macro.FCMacro --params '{"radius": 10}'
   • 设置视图：--set-view '{"view_type": "7"}'
   • 获取报告：--get-report

工具功能

以下工具功能由 freecad_mcp_client.py 提供，通过 stdio 或 TCP（localhost:9876）发送命令，由 freecad_mcp_server.py 处理。

功能	参数	描述
create_macro	macro_name，template_type	创建一个 .FCMacro 文件，验证名称（字母、数字、下划线、连字符），支持模板（default、basic、part、sketch）。
update_macro	macro_name，code	更新宏内容，自动添加 FreeCAD、FreeCADGui、Part、math 导入。
run_macro	macro_path，params（可选）	运行宏，规范化代码，重新计算文档，调整到轴测图视图。
validate_macro_code	macro_name（可选），code（可选）	验证宏代码语法，返回成功或错误（带回溯）。
set_view	params（例如，{"view_type": "7"}）	设置视图：1（前面），2（顶部），3（右侧），7（轴测图）。
get_report	无	获取服务器日志（从 %TEMP%\freecad_mcp_log.txt 和报告浏览器）。

示例

• 创建宏：

  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --create-macro gear --template-type part
  

  输出：{"status": "success", "result": "宏已创建"}

• 更新宏：

  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --update-macro gear --code "import FreeCAD, Part\nradius = 10\ngear = Part.makeCylinder(radius, 5)\nPart.show(gear)"
  

  输出：{"status": "success", "result": "宏已更新"}

• 运行宏：

  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 15}'
  

  输出：{"status": "success", "result": {...}}

• 验证代码：

  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --validate-macro-code gear --code "import FreeCAD\nApp.newDocument()"
  

  输出：{"status": "success"}

• 设置视图：

  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --set-view '{"view_type": "7"}'
  

  输出：{"status": "success", "result": "视图已设置为轴测图"}

• 获取报告：

  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report
  

  输出：{"status": "success", "result": {...}}

用例

1. 自动齿轮模型创建：

   • 场景：为工程设计生成参数化齿轮模型。
   • 步骤：
     1. 创建宏：--create-macro gear --template-type part
     2. 更新宏：--update-macro gear --code "import FreeCAD, Part\nradius = 15\ngear = Part.makeCylinder(radius, 5)\nPart.show(gear)"
     3. 运行宏：--run-macro gear.FCMacro --params '{"radius": 15}'
   • 结果：生成齿轮模型，以轴测图视图展示。
   • 输出：

2. 生成法兰模型：

   • 场景：自动化创建带有孔的法兰，用于机械设计。
   • 步骤：运行宏：--run-macro flange.FCMacro
   • 结果：生成法兰模型，自动进行规范化。
   • 输出：

3. 基于文本的模型生成：

   • 场景：根据文本描述（例如，“创建一个具有弯曲船体的船”）生成船模型。
   • 步骤：
     1. 使用 Claude 生成 boat.FCMacro。
     2. 运行宏：--run-macro boat.FCMacro
   • 结果：生成船模型，自动调整视图。
   • 输出：

4. CAD 绘图识别：

   • 场景：根据 CAD 绘图重建桌子模型。
   • 步骤：
     1. 使用 Trace 将图纸转换为 table.FCMacro。
     2. 运行宏：--run-macro table.FCMacro
   • 结果：生成桌子模型。
   • 输出：

5. 批量处理模型：

   • 场景：自动化创建多个模型（例如，齿轮和法兰）。
   • 步骤：

     for macro in gear.FCMacro flange.FCMacro; do
         python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro $macro
     done
     

   • 结果：顺序生成模型，记录到 %TEMP%\freecad_mcp_log.txt。
   • 输出：查看 gear.png 和 flange.png。

外部工具集成

FreeCAD MCP 支持与外部工具集成以增强模型生成：

• Claude：AI 模型，根据文本描述生成 .FCMacro 文件。
  • 示例：输入“创建一个半径为 10mm 的齿轮”，生成：

    import FreeCAD, Part
    radius = 10
    gear = Part.makeCylinder(radius, 5)
    Part.show(gear)
    

    保存为 gear.FCMacro，运行：--run-macro gear.FCMacro。
• Trace：CAD 绘图处理工具，将图纸转换为 .FCMacro 文件。
  • 示例：将桌子图纸转换为 table.FCMacro，运行：--run-macro table.FCMacro。
• Cursor/CodeBuddy：代码编辑工具，用于编写和调试宏代码。
  • 示例：在 Cursor 中编辑 flange.FCMacro，更新：--update-macro flange.FCMacro --code "<code>"。

资源

assets/ 目录包含以下资源：

• icon.svg：FreeCADMCPWorkbench 图标，在 InitGui.py 和 package.xml 中使用。
• gear.png：示例齿轮模型。
• flange.png：示例法兰模型。
• boat.png：示例船模型。
• table.png：示例桌子模型。
• freecad.gif：演示动画，展示图形用户界面面板、宏执行和视图切换。
• freecad.mp4：演示视频，可供下载。 下载：[FreeCAD MCP 演示 MP4](