FreeCAD MCP Server

FreeCAD MCP 服务

一个模型上下文协议（MCP）服务，可让 AI 助手使用 FreeCAD 进行 3D 建模和 CAD 操作。

功能

• 基本几何体创建：创建指定尺寸的长方体、圆柱体和球体
• 布尔运算：对对象执行并集、切割和交集运算
• 文档管理：保存文档并列出对象
• 自定义脚本执行：在 FreeCAD 环境中执行任意 Python 脚本
• 跨平台：支持 Windows、macOS 和 Linux

前置条件

1. FreeCAD 安装：从 freecad.org 安装 FreeCAD
2. Node.js：版本 18 或更高
3. TypeScript：用于开发

安装

1. 克隆此存储库：

git clone https://github.com/lucygoodchild/freecad-mcp-server.git
cd freecad-mcp-server

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 配置 FreeCAD 路径（如有需要）：
   • 服务会尝试自动检测 FreeCAD 的安装位置
   • 默认路径：
     • Windows：C:\Program Files\FreeCAD 0.21\bin\FreeCAD.exe
     • macOS：/Applications/FreeCAD.app/Contents/MacOS/FreeCAD
     • Linux：/usr/bin/freecad

使用方法

运行服务

npm start

Claude Desktop

将以下内容添加到 MCP 客户端配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）： { "mcpServers": { "freecad-mcp-server": { "command": "node", "args": ["/path/to/free-cad-mcp/build/index.js"] } } } 请确保将 "/path/to/free-cad-mcp/build/index.js" 替换为实际路径，并在完成更改后重启 Claude

可用工具

create_box

创建具有指定尺寸的长方体。

{
  "name": "create_box",
  "arguments": {
    "length": 50,
    "width": 30,
    "height": 20,
    "name": "MyBox"
  }
}

create_cylinder

创建具有指定半径和高度的圆柱体。

{
  "name": "create_cylinder", 
  "arguments": {
    "radius": 10,
    "height": 50,
    "name": "MyCylinder"
  }
}

create_sphere

创建具有指定半径的球体。

{
  "name": "create_sphere",
  "arguments": {
    "radius": 15,
    "name": "MySphere"
  }
}

boolean_operation

对两个对象执行布尔运算。

{
  "name": "boolean_operation",
  "arguments": {
    "operation": "union",
    "object1": "Box",
    "object2": "Cylinder",
    "result_name": "Combined"
  }
}

运算：union、cut、common

save_document

保存当前 FreeCAD 文档。

{
  "name": "save_document",
  "arguments": {
    "filename": "my_model.FCStd",
    "path": "/path/to/save"
  }
}

list_objects

列出当前文档中的所有对象。

{
  "name": "list_objects",
  "arguments": {}
}

execute_python_script

在 FreeCAD 环境中执行自定义 Python 脚本。

{
  "name": "execute_python_script",
  "arguments": {
    "script": "box = doc.addObject('Part::Box', 'CustomBox')\nbox.Length = 100"
  }
}

与 AI 助手集成

此服务实现了模型上下文协议，因此兼容支持 MCP 的 AI 助手。AI 可以：

1. 生成 3D 模型：通过组合基本形状创建复杂几何体
2. 参数化设计：根据需求修改尺寸和参数
3. 创建装配体：使用布尔运算构建多零件装配体
4. 设计自动化：通过脚本执行复杂建模工作流

AI 交互示例

• “创建一个轴承座，内径为 20 mm，外径为 40 mm”
• “制作一个带 M6 螺纹、长度为 50 mm 的螺栓”
• “设计一个简单支架，用于固定两根相距 30 mm 的 10 mm 杆件”

开发

项目结构

src/
  index.ts          # Main server implementation
build/              # Compiled JavaScript output
package.json        # Dependencies and scripts
tsconfig.json       # TypeScript configuration

构建

npm run build

开发模式

npm run dev

故障排除

未找到 FreeCAD

• 确认已安装 FreeCAD，且可从命令行访问
• 如有需要，更新服务构造函数中的 freecadPath
• 检查 FreeCAD 可执行文件是否具有适当的权限

脚本执行错误

• 确保 FreeCAD Python 环境包含所需模块
• 检查脚本语法——Python 脚本会在 FreeCAD 的 Python 解释器中执行
• 在执行布尔运算前，使用 list_objects 确认对象名称