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 等格式

Related MCP server: FreeCAD MCP

环境要求

重要：必须使用 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 个）

文档管理

基元创建

布尔运算

变换工具

查询/测量

导出

草图特征

项目结构

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