内容
# FreeCAD MCP 服务器
MCP（模型上下文协议）服务器，给予LLMs对FreeCAD的完全控制权 — 创建几何体，操作文档，捕捉屏幕截图，执行任意的FreeCAD Python脚本。
## 架构
```
LLM <--> MCP 服务器（FastMCP，端口 50005） <--> 桥接器（HTTP，端口 50006） <--> FreeCAD
```
两进程设计：
- **`server.py`** — 使用 [FastMCP](https://github.com/jlowin/fastmcp) 的MCP服务器。作为独立的Python进程运行。通过MCP协议向LLMs公开工具。
- **`freecad_bridge.py`** — 轻量级HTTP服务器，在FreeCAD的Python控制台内运行。通过QTimer轮询队列在FreeCAD的主线程上执行代码。
桥接器是必要的，因为FreeCAD的GUI操作必须在主线程上运行。
## 设置
### 1. 安装依赖项
```bash
pip install -r requirements.txt
```
### 2. 在FreeCAD中启动桥接器
打开FreeCAD，然后在Python控制台中：
```python
exec(open("/path/to/freecad_bridge.py").read())
```
这在FreeCAD内部启动了一个端口为50006的HTTP服务器。
#### 每次启动FreeCAD时自动启动桥接器（可选）
为了避免每次会话都粘贴到控制台中，请将桥接器注册为启动脚本。FreeCAD在启动时扫描每个`Mod/`目录，并在GUI启动后运行每个`InitGui.py` — 这正是桥接器所需要的（它导入`FreeCADGui`并启用`QtCore.QTimer`，而这些在早期App-init / `user.py`阶段都不存在）。
在`<user-app-data>/Mod/FreeCADBridge/InitGui.py`中创建文件，其中`<user-app-data>`是`FreeCAD.getUserAppDataDir()`在Python控制台中打印的内容（例如，在macOS上为`~/Library/Application Support/FreeCAD/v1-1/`）：
```python
import FreeCAD
_BRIDGE = "/path/to/freecad_bridge.py"
try:
# 在专用的命名空间字典中运行（globals IS locals）。FreeCAD exec（）带有*单独*的globals / locals字典；这里的裸exec（）会继承该分离，
# 因此桥接器的模块级名称（BRIDGE_HOST，...）将位于locals中，而其函数解析__globals__ — 在调用时引发NameError。
# 一个共享的字典避免了这种情况。
ns = {"__name__": "freecad_bridge", "__file__": _BRIDGE}
with open(_BRIDGE) as f:
exec(compile(f.read(), _BRIDGE, "exec"), ns)
FreeCAD.Console.PrintMessage("freecad-mcp bridge started from InitGui.py\n")
except Exception as e:
FreeCAD.Console.PrintError("freecad-mcp bridge autostart failed: %s\n" % e)
```
完全退出并重新打开FreeCAD，然后确认桥接器正在监听：
```bash
lsof -nP -iTCP:50006 -sTCP:LISTEN
```
### 3. 启动MCP服务器
```bash
python server.py
```
默认情况下在端口50005上运行。
### 4. 配置MCP客户端
将MCP客户端（Claude Code等）指向 `http://localhost:50005`。
## 配置
环境变量（或`.env`文件）：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MCP_HOST` | `0.0.0.0` | MCP服务器绑定地址 |
| `MCP_PORT` | `50005` | MCP服务器端口 |
| `FREECAD_BRIDGE_HOST` | `127.0.0.1` | 桥接器服务器地址 |
| `FREECAD_BRIDGE_PORT` | `50006` | 桥接器服务器端口 |
## 工具
### 文档管理
- `create_document`，`open_document`，`save_document`，`close_document`
- `list_documents`，`set_active_document`，`get_document_objects`
### 几何体和零件设计
- `create_body`，`create_sketch`，`create_pad`，`create_pocket`
- `create_box`，`create_cylinder`，`create_sphere`，`create_cone`，`create_torus`
- `create_fillet`，`create_chamfer`，`create_revolution`，`create_groove`
- `boolean_fuse`，`boolean_cut`，`boolean_common`
### 草图操作
- `sketch_add_line`，`sketch_add_rectangle`，`sketch_add_circle`，`sketch_add_arc`
- `sketch_add_constraint`
### 装配
- `create_assembly`，`assembly_add_part`，`assembly_insert_object`
- `assembly_create_joint`，`assembly_delete_joint`，`assembly_list_joints`
- `assembly_ground_part`，`assembly_set_part_placement`，`assembly_solve`
### 检查和测量
- `get_tree`，`get_object_properties`
- `get_face_info`，`get_edge_info`，`find_faces_by_criteria`，`find_edges_by_criteria`
- `measure_distance`，`measure_angle`，`measure_between_objects`
### 屏幕截图和相机
- **`screenshot`** — 捕捉当前视图。返回多个图像（默认：平面线 + 隐藏线）。支持`styles`参数进行自定义绘制样式。
- **`screenshot_multiview`** — 捕捉标准视图（正面，顶部，右侧，等距视图等）。每个视图返回N个图像。支持`styles`参数。
- `get_camera`，`set_camera`
#### 绘制样式
两种屏幕截图工具都接受`styles`参数：
```
styles="flat_lines" # 单个样式
styles="flat_lines,wireframe" # 两个样式
styles="flat_lines,hidden_line,wireframe" # 三个样式
```
可用样式：`flat_lines`（6），`hidden_line`（3），`wireframe`（2），`shaded`（5），`no_shading`（4），`points`（1）。
默认值：`flat_lines,hidden_line`。
### 变换
- `set_placement`，`translate_object`，`rotate_object`
- `copy_object`，`delete_object`，`set_label`，`set_color`
### 脚本执行
- **`run_script`** — 执行任意的FreeCAD Python代码。对`FreeCAD`，`Part`，`FreeCADGui`等具有完全访问权限。设置`__result__`以返回数据。
## 文件结构
```
server.py # MCP服务器入口点
freecad_bridge.py # HTTP桥接器（在FreeCAD内部运行）
bridge_client.py # 桥接器的异步HTTP客户端
requirements.txt
tools/
__init__.py # 工具注册
_helpers.py # 共享实用程序
assembly.py # 装配工具
camera.py # 相机获取/设置
document.py # 文档管理
geometry.py # 布尔运算，圆角，倒角
inspection.py # 树，属性，面/边查询
measurement.py # 距离，角度测量
partdesign.py # 草图，填充，挖槽，旋转
primitives.py # 盒子，圆柱体，球体，圆锥体，环形体
screenshot.py # 屏幕截图捕捉，带有绘制样式控制
script.py # 任意脚本执行
transform.py # 放置，移动，旋转，复制，删除
```
## 许可证
MIT
