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. 克隆项目

git clone https://github.com/your-username/freecad-mcp.git
cd freecad-mcp

2. 安装 MCP 依赖

# 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 中添加：

{
  "mcp": {
    "freecad-modeling": {
      "type": "local",
      "command": ["bash", "/path/to/freecad-mcp/run_mcp.sh"],
      "enabled": true
    }
  }
}

Cline / Cursor

{
  "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