使用说明

FreeCAD MCP插件

这个 FreeCAD MCP 插件集成了 模型控制协议（MCP） FreeCAD，通过服务器-客户端架构实现模型创建、宏执行和视图管理的自动化。它提供了一个GUI控制面板和一个命令行客户端来简化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)以及宏的执行后步骤（重新计算、视图调整）。
GUI控制面板：包括启动/停止服务器、清除日志和切换视图（正面、顶部、右侧、轴测）的按钮。
记录系统：将消息和错误记录到 freecad_mcp_log.txt 在临时目录中（例如。， %TEMP%\freecad_mcp_log.txt)以及GUI报告浏览器（100行限制）。
工作台集成：添加一个 FreeCADMCPWorkbench 使用工具栏和菜单命令（在中实现 InitGui.py).
视觉资产：包括工作台图标(icon.svg)，示例模型(gear.png, flange.png, boat.png, table.png)，以及演示动画(freecad.gif, freecad.mp4).

观看演示动画：下载演示视频： FreeCAD MCP演示MP4

快速开始

安装插件（请参阅安装).
启动FreeCAD并切换到 FreeCAD MCP 工作台。
打开控制面板(FreeCAD_MCP_Show)然后单击“启动服务器”

运行一个示例宏：

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

查看结果：生成齿轮模型并以轴测视图显示。

安装

先决条件

FreeCAD：0.21或更高版本，下载FreeCAD。选择操作系统的版本。
python：3.12+版本（包含在FreeCAD中或通过Anaconda安装）。
蟒蛇（建议用于依赖关系管理）：下载Anaconda。选择操作系统的版本。
Python依赖关系:
- 所需软件包： mcp-server （在 pyproject.toml).
- 安装命令：
```
# use system Python
pip install mcp-server
```
- 验证安装：
```
pip show mcp-server 
```
  确保 mcp-server 版本。

安装步骤

克隆仓库:

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

复制到FreeCAD Mod目录: 复制 FreeCAD-MCP 文件夹到：
- 窗户： D:\FreeCAD\Mod\FreeCAD-MCP
- Linux： ~/.local/share/FreeCAD/Mod/FreeCAD-MCP
- macOS： ~/Library/Application Support/FreeCAD/Mod/FreeCAD-MCP
```
# Windows example
xcopy FreeCAD-MCP D:\FreeCAD\Mod\FreeCAD-MCP /E /H /C /I
```
备注：调整 D:\FreeCAD\Mod 基于您的FreeCAD安装路径。
启动FreeCAD:
- 打开FreeCAD并切换到 FreeCAD MCP 工作台（图标： assets/icon.svg).
- 核实一下 FreeCAD-MCP 已加载 编辑>首选项>附加组件.
验证安装:
- 点击 FreeCAD_MCP_Show 打开控制面板。
- 检查临时目录（例如。， %TEMP%\freecad_mcp_log.txt)用于启动消息。

MCP配置

配置MCP客户端以通过以下方式与FreeCAD通信 stdio 或TCP。

创建配置文件: 创建 mcp_config.json 在 D:\FreeCAD\Mod\FreeCAD-MCP-main\src\:
```
{
    "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"]
        }
    }
}
```
备注:
- 根据您的系统调整路径：
  - 蟒蛇之路例如。， 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.
运行服务器:
- GUI方法：在 FreeCAD MCP 工作台，单击 FreeCAD_MCP_Show 然后“启动服务器”
- 命令行方法:
```
conda activate freecad_mcp
python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_server.py
```
验证服务器:
- 检查 %TEMP%\freecad_mcp_log.txt 显示“服务器已启动”消息。
- 测试客户端命令：
```
python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report
```

用法

GUI使用

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

命令行用法

激活Anaconda环境：
```
conda activate freecad_mcp
```
运行客户端命令：
```
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": "Macro created"}

更新宏:

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": "Macro updated"}

运行宏:

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": "view set to axonometric"}

获取报告:

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

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

用例

自动齿轮模型创建:
- 场景：为工程设计生成参数化齿轮模型。
- 步骤:
  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}'
- 结果：生成齿轮模型，以轴测图显示。
- 输出:
生成法兰模型:
- 场景：自动创建带孔的法兰，用于机械设计。
- 步骤：运行宏： --run-macro flange.FCMacro
- 结果：通过自动归一化生成的法兰模型。
- 输出:
基于文本的模型生成:
- 场景：根据文本描述生成船模型（例如，“创建具有弯曲船体的船”）。
- 步骤:
  1. 使用Claude生成 boat.FCMacro.
  2. 运行宏： --run-macro boat.FCMacro
- 结果：通过自动视图调整生成的船模型。
- 输出:
CAD图形识别:
- 场景：从CAD图形中重新创建表格模型。
- 步骤:
  1. 使用Trace将图形转换为 table.FCMacro.
  2. 运行宏： --run-macro table.FCMacro
- 结果：生成表格模型。
- 输出:
批处理模型:
- 场景：自动创建多个模型（例如齿轮和法兰）。
- 步骤:
```
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支持与外部工具集成，以增强模型生成：

克劳德：用于生成的AI模型 .FCMacro 从文本描述中提取文件。
- 示例：输入“创建半径为10mm的齿轮”，生成：
```
import FreeCAD, Part
radius = 10
gear = Part.makeCylinder(radius, 5)
Part.show(gear)
```
  另存为 gear.FCMacro，运行： --run-macro gear.FCMacro.
追踪：CAD绘图处理工具，用于将绘图转换为 .FCMacro 文件夹。
- 示例：将表格图形转换为 table.FCMacro，运行： --run-macro table.FCMacro.
光标/代码伙伴：用于编写和调试宏代码的代码编辑工具。
- 示例：编辑 flange.FCMacro 在游标中，更新： --update-macro flange.FCMacro --code "<code>".

资产

这个 assets/ 目录包含以下资源：

icon.svg：图标 FreeCADMCPWorkbench，用于 InitGui.py 和 package.xml.
齿轮.png：齿轮型号示例。
flange.png：法兰模型示例。
船.png：船模型示例。
表.png：示例表模型。
freecad.gif：演示动画，显示GUI面板、宏执行和视图切换。
freecad.mp4：演示视频，可供下载。下载： FreeCAD MCP演示MP4

故障排除

服务器无法启动:
- 问题：端口9876正在使用中。
- 解决方案：检查端口(netstat -ano | findstr 9876)、更改端口或终止冲突进程。
客户端连接失败:
- 问题：中的路径不正确 mcp_config.json.
- 解决方案：验证 command 和 args 路径。， D:\Anaconda3\python.exe 和 D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py.
宏执行错误:
- 问题：宏代码中存在语法错误或缺少导入。
- 解决方案：使用 --validate-macro-code 要检查代码，请在中查看回溯 %TEMP%\freecad_mcp_log.txt.
未生成日志文件:
- 问题：临时目录中没有写入权限。
- 解决方案：检查的权限 %TEMP%\freecad_mcp_log.txt，或在中指定其他路径 freecad_mcp_server.py.
更多帮助：在GitHub上提交问题(错误追踪系统).

贡献

欢迎投稿！请按照以下步骤操作：

分叉存储库： https://github.com/ATOI-Ming/FreeCAD-MCP.
创建分支： git checkout -b feature/your-feature.
提交更改： git commit -m "Add your feature".
推送并创建拉取请求。

如有疑问或合作，请打开问题或联系[1757772673@qq.com,抖音：胡胡舒学95]

许可证

该项目根据MIT许可证获得许可。看许可证了解详情。

使用说明

FreeCAD MCP插件

目录

特征

快速开始

安装

先决条件

安装步骤

MCP配置

用法

GUI使用

命令行用法

工具功能

例子

用例

外部工具集成

资产

故障排除

贡献

许可证

相关 MCP

Rhino与Grasshopper AI控制MCP服务

Blender 3D建模MCP服务

3D资产生成服务

CAD控制服务器

Blender远程自动化工具

Rhino 3D建模工具