FreeCAD-MCP

GMing123/FreeCAD-MCP

0 Stars 140 次浏览更新于 2026-08-23

FreeCAD MCP 插件将模型控制协议 (MCP) 集成到 FreeCAD 中，通过服务器-客户端架构实现模型创建、宏执行和视图管理的自动化。它提供了一个带有 GUI 控制面板的 MCP 服务器和一个客户端接口，以简化 FreeCAD 工作流程，支持运行宏、调整视图以及与外部工具集成等任务。

开发者工具

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

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

服务介绍

FreeCAD MCP 插件

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

功能

FreeCAD MCP 插件 (v0.1.0) 提供了以下功能：

MCP 服务器：提供一个 GUI 控制面板 (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_client.py)。
GUI 控制面板：包括启动/停止服务器、清除日志和切换视图（前视图、顶视图、右视图、轴测图）的按钮 (freecad_mcp_server.py)。
日志记录：将消息和错误记录到 freecad_mcp_log.txt 和 GUI 报告浏览器中（限制 100 行）。
工作台集成：添加一个包含工具栏/菜单命令的 FreeCADMCPWorkbench (InitGui.py)。
视觉资源：包括工作台图标 (icon.svg)、示例模型 (gear.png、flange.png、boat.png、table.png) 和演示动画 (freecad.gif)。

观看演示：

下载：FreeCAD MCP 演示 MP4

安装

按照以下步骤安装并设置 FreeCAD MCP 插件。

前提条件

FreeCAD：版本 0.21 或更高。下载 FreeCAD。
Python：版本 3.8+（随 FreeCAD 一起提供或通过 Anaconda 获取）。
Anaconda（推荐，用于依赖项管理）：下载 Anaconda。
Python 依赖项：
- 所需包：mcp-server>=1.2.0，httpx>=0.24.1（在 pyproject.toml 中指定）。
- 安装（在 Anaconda 环境中）：
  bash
  conda activate freecad_mcp
  pip install mcp-server>=1.2.0 httpx>=0.24.1
- 替代方案（不使用 Anaconda，使用系统 Python）：
  bash
  python -m pip install mcp-server>=1.2.0 httpx>=0.24.1
- 验证安装：
  bash
  pip show mcp-server
  pip show httpx
  
  确保 mcp-server 版本 >=1.2.0 且 httpx 版本 >=0.24.1。如果未安装，请重复 pip install 命令。

安装步骤

克隆仓库：

bash
git clone https://github.com/ATOI-Ming/FreeCAD-MCP.git
复制到 FreeCAD Mod 目录：

将 FreeCAD-MCP 文件夹移动到 FreeCAD 的 Mod 目录中：
- Windows: C:\Users\<YourUser>\AppData\Roaming\FreeCAD\Mod\
- Linux: ~/.local/share/FreeCAD/Mod/
- macOS: ~/Library/Application Support/FreeCAD/Mod/
bash
cp -r FreeCAD-MCP C:\Users<YourUser>\AppData\Roaming\FreeCAD\Mod\
设置 Anaconda 环境（推荐）：

创建并激活一个新的 Anaconda 环境：

bash
conda create -n freecad_mcp python=3.8
conda activate freecad_mcp安装依赖项（已在先决条件中介绍，此处重复说明以确保清晰）：

bash
pip install mcp-server>=1.2.0 httpx>=0.24.1

启动 FreeCAD：
- 打开 FreeCAD。
- 从工作台下拉菜单中切换到 FreeCADMCPWorkbench（图标：assets/icon.svg）。
验证安装：
- 确认 FreeCADMCPWorkbench 出现在 FreeCAD 中。
- 单击 FreeCAD_MCP_Show 以打开控制面板或单击 FreeCAD_MCP_RunMacro 以测试宏执行。
- 检查 D:\FreeCAD\Mod\FreeCAD-MCP-main\ 目录下的 freecad_mcp_log.txt 文件中的启动消息。

MCP 配置

配置 MCP 客户端以使用 Anaconda 的 Python 运行 freecad_mcp_client.py，以便通过 stdio 与 FreeCAD 通信。

创建配置文件：

在 D:\FreeCAD\Mod\FreeCAD-MCP-main\ 目录下创建一个 JSON 文件（例如 mcp_config.json）：

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

注意事项：
- 根据您的系统调整路径：
  - Linux: /home/<user>/anaconda/bin/python, /home/<user>/.local/share/FreeCAD/Mod/FreeCAD-MCP-main/src/freecad_mcp_client.py
  - macOS: /Users/<user>/anaconda/bin/python, /Users/<user>/Library/Application Support/FreeCAD/Mod/FreeCAD-MCP-main/src/freecad_mcp_client.py
- 该配置运行 freecad_mcp_client.py 以通过 stdio 与 FreeCAD 通信。
运行服务器：
- 图形界面方法：在 FreeCADMCPWorkbench 中，单击 FreeCAD_MCP_Show 以启动 MCP 服务器 (freecad_mcp_server.py) 并打开控制面板。
- 命令行方法：
  bash
  conda activate freecad_mcp
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\freecad_mcp_server.py
验证服务器：
- 检查 D:\FreeCAD\Mod\FreeCAD-MCP-main\ 目录下的 freecad_mcp_log.txt 文件中的启动消息（例如，“Server started”）。
- 确保服务器对客户端命令有响应（例如，freecad_mcp_client.py --get-report）。

使用方法

使用 GUI 控制面板

在 FreeCAD 中，切换到 FreeCADMCPWorkbench（图标：assets/icon.svg）。
单击 FreeCAD_MCP_Show 以打开控制面板 (FreeCADMCPPanel)。
使用面板：
- 启动/停止服务器：启动或停止 MCP 服务器 (freecad_mcp_server.py)。
- 清除日志：清除报告浏览器和 freecad_mcp_log.txt。
- 视图按钮：切换到前视图、顶视图、右视图或轴测视图。
在报告浏览器中监控日志（每秒通过 QTimer 更新一次）。

运行宏

图形界面方法：
- 在 FreeCADMCPWorkbench 中，单击 FreeCAD_MCP_RunMacro。
- 使用文件对话框选择一个 .FCMacro 文件。
- 宏将自动标准化后运行（添加导入、重新计算文档、调整视图）。
命令行方法：
- 激活 Anaconda 环境：
  bash
  conda activate freecad_mcp
- 运行宏：
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro path/to/macro.FCMacro
- 带参数运行：
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 10}'

远程控制

使用 freecad_mcp_client.py 向 MCP 服务器发送命令：

bash
python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --set-view 7
python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report

工具功能插件提供了以下工具函数，这些函数在 `freecad_mcp_client.py` 中实现（用于通过 `stdio` 或 TCP 向 `localhost:9876` 发送命令），并在 `freecad_mcp_server.py` 中处理（用于在 FreeCAD 中处理命令）。这些功能使用户能够远程控制 FreeCAD 进行宏操作、代码验证和视图调整。

主要工具函数

create_macro:
- 描述: 使用指定模板创建一个新的 FreeCAD 宏文件（.FCMacro）。
- 参数:
  - macro_name: 宏文件的名称（例如，my_macro.FCMacro）。
  - template_type: 模板类型（default、basic、part、sketch）。
- 用法:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --create-macro my_macro.FCMacro --template-type default
- 输出: JSON 对象确认宏创建成功或错误（例如，{"status": "success", "result": "Macro created"} 或 {"status": "error", "message": "..."}）。
- 实现:
  - 客户端 (freecad_mcp_client.py)：生成带有预定义模板代码的宏文件，并通过 stdio 或 TCP 发送创建请求。
  - 服务器 (freecad_mcp_server.py)：处理请求（假设通过 handle_create_macro 处理）。
update_macro:
- 描述: 更新现有 FreeCAD 宏文件（.FCMacro）的内容。
- 参数:
  - macro_name: 要更新的宏文件的名称（例如，my_macro.FCMacro）。
  - code: 宏的新代码内容。
- 用法:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --update-macro my_macro.FCMacro --code "import FreeCAD\nApp.newDocument()"
- 输出: JSON 对象确认更新成功或错误（例如，{"status": "success", "result": "Macro updated"} 或 {"status": "error", "message": "..."}）。
- 实现:
  - 客户端：通过 stdio 或 TCP 发送带有新代码的更新请求。
  - 服务器：处理请求（假设通过 handle_update_macro 处理）。
run_macro:
- 描述: 执行一个 FreeCAD 宏文件，通过添加导入（FreeCAD、FreeCADGui、Part、math）和执行后步骤（重新计算文档、设置轴测视图、适应视图）来规范化代码。
- 参数:
  - macro_path: .FCMacro 文件的路径（例如，path/to/macro.FCMacro）。
  - params: 可选的 JSON 字符串，用于宏参数（例如，{"radius": 10}）。
- 用法:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro macro.FCMacro --params '{"radius": 10}'
- 输出: JSON 对象包含执行结果或错误，如果失败则包括回溯信息（例如，{"status": "success", "result": {...}} 或 {"status": "error", "message": "...", "result": {"traceback": "..."}}）。
- 实现:
  - 客户端：通过 normalize_macro_code 规范化宏代码，通过 stdio 或 TCP 发送 {"type": "run_macro", "params": {"code": normalized_code, ...}}。
  - 服务器：通过 handle_run_macro 执行规范化后的代码并返回结果。
validate_macro_code:
- 描述: 验证 FreeCAD 宏文件或代码片段的语法和运行时正确性。
- 参数:
  - macro_name: 宏文件的名称（例如，my_macro.FCMacro）或 code（直接代码字符串）。
- 用法:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --validate-macro-code macro.FCMacro
- 输出: JSON 对象指示验证结果或错误（例如，{"status": "success"} 或 {"status": "error", "message": "..."}）。
- 实现:
  - 客户端：使用 ast 或 try-except 解析代码（从 run_macro 错误处理中推断），检查语法和导入。
  - 服务器：可能协助验证（假设通过 handle_validate_macro_code 处理）。
set_view:
- 描述: 将 FreeCAD 3D 视图调整到指定视角（前视图、顶视图、右视图或轴测视图）。- Parameters:
- view_type: 视图类型（1 为前视图，2 为顶视图，3 为右视图，7 为轴测视图）。
Usage:
bash
python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --set-view 7
Output: JSON 对象确认视图更改或错误（例如，{"status": "success", "result": "view set to axonometric"} 或 {"status": "error", "message": "Invalid view type"}）。
Implementation:
- 客户端：验证 view_type（1, 2, 3, 7），通过 stdio 或 TCP 发送 {"type": "set_view", "params": {"view_type": view_type}}。
- 服务器：通过 handle_set_view 调整视图，并返回确认信息。
get_report:
- Description: 从 freecad_mcp_log.txt 中检索执行和验证报告。
- Parameters: 无。
- Usage:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report
- Output: 包含日志内容的 JSON 对象（例如，{"status": "success", "result": {...}}）。
- Implementation:
  - 客户端：通过 stdio 或 TCP 发送 {"type": "get_report", "params": {}}。
  - 服务器：通过 handle_get_report 读取日志文件并返回内容。

辅助功能

日志系统:
- 描述: 将操作和错误记录到 freecad_mcp_log.txt 和 GUI 报告浏览器中（限制 100 行）。
- 实现:
  - 服务器: 使用 log_message 记录标准消息，使用 log_error 记录带 HTML 格式的错误消息在 GUI 中显示。
  - 日志包括时间戳，并追加到文件并在报告浏览器中显示。
服务器管理:
- 描述: 启动/停止 MCP 服务器，在 localhost:9876 上监听 TCP 连接。
- 实现:
  - 服务器: FreeCADMCPServer 类管理服务器生命周期（start 和 stop 方法）。
  - GUI: FreeCADMCPPanel 提供启动/停止按钮。
GUI 面板:
- 描述: 提供一个图形控制面板 (FreeCADMCPPanel) 用于服务器控制、日志管理和视图切换。
- 实现:
  - 服务器: 使用 PySide2 创建一个对话框，包含启动/停止服务器、清除日志和切换视图（前视图、顶视图、右视图、轴测视图）的按钮。
  - 每秒更新一次以实现实时日志显示。
错误处理:
- 描述: 在命令执行、验证和服务器操作期间捕获并报告异常。
- 实现:
  - 客户端: 使用 try-except 捕获 JSON 解析、套接字连接和执行错误，返回带有跟踪信息的 JSON 错误对象。
  - 服务器: 通过 log_error 记录错误，并在 GUI 中以红色 HTML 格式显示。

用例

1. 自动化齿轮模型创建

场景: 为工程设计程序化地创建齿轮模型。
步骤:
1. 创建宏文件:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --create-macro gear.FCMacro --template-type part
2. 更新宏:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --update-macro gear.FCMacro --code "import FreeCAD, Part\nradius = 10\ngear = Part.makeCylinder(radius, 5)\nPart.show(gear)"
3. 运行宏:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 15}'
4. 结果: 创建齿轮模型，重新计算并在轴测视图中显示。
输出:

2. 生成法兰模型

场景: 自动化创建带孔的法兰模型，用于机械设计。
步骤:
1. 通过 GUI (FreeCAD_MCP_RunMacro) 或命令行创建并运行宏:
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro flange.FCMacro
2. 结果: 创建标准化代码的法兰模型。
输出:

3. 基于文本的模型生成

场景: 从文本描述生成船模型（例如，“创建一艘带有弯曲船体的船”）。
步骤：
1. 使用外部工具（例如，Claude）生成 boat.FCMacro。
2. 运行宏：
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro boat.FCMacro
3. 结果：自动导入并调整视图后创建了船模型。
输出：

4. CAD 图纸识别

场景: 从 CAD 图纸重新创建一个桌子模型。
步骤：
1. 使用类似 Trace 的工具将 CAD 图纸转换为 table.FCMacro。
2. 通过 GUI 或命令行运行：
  bash
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro table.FCMacro
3. 结果：在 FreeCAD 中重新创建了桌子模型。
输出：

5. 批量处理模型

场景: 自动创建多个模型（例如，齿轮和法兰）。
步骤：
1. 创建一个脚本来循环运行宏：
  bash
  for macro in gear.FCMacro flange.FCMacro; do
  python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro $macro
  done
2. 结果：依次生成模型，并记录在 freecad_mcp_log.txt 中。

资源

assets/ 目录包含 FreeCAD MCP 插件的可视化和演示资源：

icon.svg: FreeCADMCPWorkbench 的工作台和命令图标，用于 InitGui.py 和 package.xml。
gear.png: 通过 run_macro 生成的齿轮模型示例。
flange.png: 工程设计用的法兰模型示例。
boat.png: 从基于文本的生成中得到的船模型示例。
table.png: 从 CAD 图纸识别中得到的桌子模型示例。
freecad.gif: 演示动画，展示了 GUI 面板、宏执行和视图切换。
观看：
freecad.mp4: 原始演示视频，可供下载。
下载: FreeCAD MCP 演示 MP4

贡献

欢迎贡献！要贡献代码，请按照以下步骤操作：

分叉仓库: https://github.com/ATOI-Ming/FreeCAD-MCP。
创建分支: git checkout -b feature/your-feature。
提交更改: git commit -m "Add your feature"。
推送并创建 Pull Request。

请遵循行为准则（待添加）。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE。

查看源码项目主页