内容
# FreeCAD MCP Server
让 AI（如 Cline、Cursor、opencode）通过 MCP 协议直接调用 FreeCAD 进行 3D 建模。
## 概述
本项目是一个 **MCP (Model Context Protocol) Server**，封装了 FreeCAD 的 Python API，提供 39 个建模工具，让 AI 能够：
- 创建/编辑/查询 3D 模型
- 执行布尔运算（切割、合并、相交）
- 变换对象（平移、旋转、镜像、缩放）
- 草图拉伸/旋转生成实体
- 测量几何属性（体积、面积、质心、包围盒）
- 导出为 STEP / STL / OBJ / BREP / IGES / FCStd 等格式
## 环境要求
| 组件 | 要求 |
|------|------|
| FreeCAD | 1.1.x 或更高版本 |
| Python | FreeCAD 自带的 Python（不能用系统 Python） |
| MCP SDK | `mcp>=1.28.0` |
> **重要**：必须使用 FreeCAD 自带的 Python，因为 `FreeCAD.pyd` / `FreeCAD.so` 是 C++ 扩展，只能在 FreeCAD 的 Python 环境中加载。
## 快速开始
### 1. 克隆项目
```bash
git clone https://github.com/your-username/freecad-mcp.git
cd freecad-mcp
```
### 2. 安装 MCP 依赖
```bash
# macOS / Linux
/Applications/FreeCAD.app/Contents/Resources/bin/python -m pip install mcp
# Windows
E:\Freecad\bin\python.exe -m pip install mcp
```
### 3. 配置 MCP 客户端
#### opencode
在 `~/.config/opencode/opencode.json` 中添加：
```json
{
"mcp": {
"freecad-modeling": {
"type": "local",
"command": ["bash", "/path/to/freecad-mcp/run_mcp.sh"],
"enabled": true
}
}
}
```
#### Cline / Cursor
```json
{
"mcpServers": {
"freecad-modeling": {
"command": "bash",
"args": ["/path/to/freecad-mcp/run_mcp.sh"],
"cwd": "/path/to/freecad-mcp"
}
}
}
```
> **Windows 用户**：使用 `run_server.bat` 替代 `run_mcp.sh`
### 4. 重启 MCP 客户端
配置后重启客户端，即可在对话中让 AI 使用 FreeCAD 建模工具。
## 使用示例
对 AI 说：
> "帮我建一个 20×15×10 的盒子，然后在中心打一个半径 3 的通孔，导出为 STEP 文件。"
AI 会自动调用：
1. `new_document` → 新建文档
2. `create_box(20, 15, 10)` → 创建盒子
3. `create_cylinder(3, 10)` → 创建圆柱
4. `translate("Cylinder", 10, 7.5, 0)` → 移动到中心
5. `boolean_cut("Box", "Cylinder")` → 布尔切割
6. `export_step("output/part.step")` → 导出
## 可用工具（39 个）
### 文档管理
| 工具 | 说明 |
|------|------|
| `new_document` | 新建文档 |
| `open_document` | 打开 .FCStd 文件 |
| `save_document` | 保存文档 |
| `close_document` | 关闭文档 |
| `list_documents` | 列出所有打开的文档 |
| `list_objects` | 列出文档中的对象 |
| `get_active_document` | 获取活动文档信息 |
### 基元创建
| 工具 | 说明 |
|------|------|
| `create_box` | 创建长方体 |
| `create_cylinder` | 创建圆柱体 |
| `create_sphere` | 创建球体 |
| `create_cone` | 创建圆锥/圆台 |
| `create_torus` | 创建圆环 |
| `create_prism` | 创建正棱柱 |
### 布尔运算
| 工具 | 说明 |
|------|------|
| `boolean_cut` | 差集（切割） |
| `boolean_fuse` | 并集（合并） |
| `boolean_intersect` | 交集 |
| `boolean_compound` | 组合为复合体 |
### 变换工具
| 工具 | 说明 |
|------|------|
| `translate` | 平移 |
| `rotate` | 旋转 |
| `mirror` | 镜像 |
| `scale_object` | 缩放 |
| `set_placement` | 设置位置+姿态 |
### 查询/测量
| 工具 | 说明 |
|------|------|
| `get_object_info` | 获取对象详细信息 |
| `measure_volume` | 测量体积 |
| `measure_area` | 测量表面积 |
| `bounding_box` | 获取包围盒 |
| `center_of_mass` | 获取质心 |
| `check_validity` | 检查几何有效性 |
### 导出
| 工具 | 说明 |
|------|------|
| `export_step` | 导出 STEP |
| `export_stl` | 导出 STL |
| `export_obj` | 导出 OBJ |
| `export_brep` | 导出 BREP |
| `export_iges` | 导出 IGES |
| `save_fcstd` | 保存为 FCStd |
### 草图特征
| 工具 | 说明 |
|------|------|
| `create_sketch_extrude` | 轮廓拉伸 |
| `create_sketch_revolve` | 轮廓旋转 |
| `create_hollow_cylinder` | 空心圆柱 |
| `fillet_edges` | 倒圆角 |
| `chamfer_edges` | 倒角 |
## 项目结构
```
freecad-mcp/
├── main.py # 入口
├── freecad_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server + 工具注册
│ ├── runner.py # 安全执行 + JSON 封装
│ └── tools/
│ ├── document.py # 文档管理
│ ├── primitives.py# 基元创建
│ ├── boolean.py # 布尔运算
│ ├── transform.py # 变换
│ ├── measure.py # 查询/测量
│ ├── export.py # 导出
│ └── sketch.py # 草图特征
├── scripts/
│ └── test_basic.py # 冒烟测试
├── output/ # 导出文件输出目录
├── run_mcp.sh # macOS/Linux 启动脚本
├── run_server.bat # Windows 启动脚本
├── requirements.txt
└── README.md
```
## 技术说明
- **传输方式**：stdio（标准 MCP 传输）
- **运行环境**：FreeCAD 自带 Python，3.11+
- **无 GUI 模式**：server 在无 GUI 环境下运行，导出使用 Part 模块
- **单位**：所有尺寸默认为毫米(mm)
- **坐标系**：右手坐标系，Z 轴向上
## 常见问题
### Q: 为什么不用系统 Python？
FreeCAD 的 Python 扩展是 C++ 编译的，只兼容 FreeCAD 自带的 Python 环境。系统 Python 无法 `import FreeCAD`。
### Q: macOS 上如何找到 FreeCAD Python？
通常在：
```
/Applications/FreeCAD.app/Contents/Resources/bin/python
```
### Q: 如何修改 FreeCAD 安装路径？
编辑 `run_mcp.sh`（macOS/Linux）或 `run_server.bat`（Windows），修改 Python 路径即可。
### Q: 导出 STL/OBJ 失败？
确保使用 `freecadcmd` 或正确配置 `PYTHONPATH`。代码已处理无 GUI 环境的导出。
## License
MIT
