内容
# bambu-cli-mcp
通过[MCP](https://modelcontextprotocol.io)实现AI原生3D打印流程。 将自然语言转化为可打印的制造包。
两个MCP服务器暴露了22种工具，它们将网格几何操作和BambuStudio CLI编排链接成声明式制造工作流——从STL到切片、分割、带有连接器的3MF项目。
**[文档](https://catesandrew.github.io/bambu-cli-mcp)** | **[架构决策](docs/adr/)** | **[示例](examples/)**
## 功能描述
```
"将这个坡道缩放至400%并为我的Bambu X1E进行分割"
|
v
检查网格（水密检查，尺寸）
|
修复网格（修复法线，合并顶点）
|
缩放网格（统一4倍）
|
分割网格（递归直到所有零件适合256mm）
|
添加连接器（表面验证，12mm连接器）
|
BambuStudio CLI（定向，排列，导出3MF每个零件）
|
v
36个可打印的3MF文件 + 装配清单
```
## 快速入门
### 前提条件
- 已安装 [BambuStudio](https://bambulab.com/en/download/studio)
- Node.js >= 20
- pnpm
### 安装
```bash
git clone https://github.com/catesandrew/bambu-cli-mcp.git
cd bambu-cli-mcp
pnpm install
pnpm build
```
### 配置你的MCP客户端
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"bambu-cli-mcp": {
"command": "node",
"args": ["/path/to/bambu-cli-mcp/dist/index.js", "--server", "both"]
}
}
}
```
**Claude Code** (`.claude/settings.json`):
```json
{
"mcpServers": {
"bambu-cli-mcp": {
"command": "node",
"args": ["/path/to/bambu-cli-mcp/dist/index.js", "--server", "both"]
}
}
}
```
`--server`标志选择要加载的工具：
| 标志 | 工具 | 用例 |
|------|-------|----------|
| `bambu` | 11个BambuStudio工具 | 仅切片和导出 |
| `geometry` | 11个几何工具 | 仅网格处理 |
| `both` | 所有22个工具 | 完整流程 |
## 工具
### BambuStudio工具（11个）
| 工具 | 描述 |
|------|-------------|
| `inspect_bambu_cli` | 返回BambuStudio版本、路径和可用的CLI标志 |
| `convert_to_3mf` | 将STL/OBJ文件转换为.3mf项目 |
| `arrange_project` | 自动在构建板上排列对象 |
| `orient_project` | 自动定向对象以优化打印 |
| `slice_project` | 使用指定设置切片项目 |
| `export_plate_png` | 导出板块的PNG预览图像 |
| `export_stls` | 导出对象为单独的STL文件 |
| `export_settings` | 将BambuStudio设置导出为JSON |
| `validate_project` | 验证项目并报告信息/警告 |
| `estimate_print` | 估计打印时间和耗材使用 |
| `create_print_package` | 完整流程：转换、排列、定向、切片、预览 |
### 几何工具（11个）
**核心：**
| 工具 | 描述 |
|------|-------------|
| `inspect_mesh` | 界限、三角形数量、体积、水密状态、亏格 |
| `repair_mesh` | 修复法线、合并顶点、移除退化面 |
| `scale_mesh` | 按任意因子统一缩放 |
| `split_mesh` | 递归分割直到所有零件适合构建体积 |
| `lay_flat` | 将最大平面定向到构建板上 |
| `add_dowel_connectors` | 在分割缝隙上添加表面验证的连接器 |
| `generate_assembly_manifest` | 零件、邻居、连接器、硬件列表 |
**工作流：**
| 工具 | 描述 |
|------|-------------|
| `make_printable_large_model` | 检查 -> 缩放 -> 修复 -> 分割 -> 连接器 -> 清单 |
| `repair_and_prepare` | 检查 -> 修复 -> 放置平面 |
| `split_with_connectors` | 分割 -> 连接器 -> 清单 |
| `list_available_engines` | 检测可用的CAD引擎 |
## 示例
### 检查网格
```json
{
"tool": "inspect_mesh",
"arguments": { "path": "/models/ramp.stl" }
}
```
返回：
```json
{
"bounds": { "min": [-5, -5, 0], "max": [5, 5, 10], "size": [10, 10, 10] },
"triangleCount": 12,
"volume": 1000,
"watertight": true,
"genus": 0
}
```
### 缩放和分割以进行打印
```json
{
"tool": "make_printable_large_model",
"arguments": {
"input": "/models/ramp.stl",
"scale": 4,
"buildVolume": [256, 256, 256],
"connector": {
"type": "dowel",
"diameterMm": 12,
"depthMm": 25,
"clearanceMm": 0.2,
"countPerSeam": 4
},
"outputDir": "outputs/"
}
}
```
### 切片3MF项目
```json
{
"tool": "slice_project",
"arguments": {
"project": "/path/to/model.3mf",
"plate": 0,
"settings": {
"machine": "profiles/printers/bambu_x1e.json",
"process": "profiles/process/petg_strong_030.json",
"filaments": ["profiles/filament/petg.json"]
}
}
}
```
参见 [`examples/`](examples/) 获取更多工作流示例。
## 架构
```
LLM 客户端（Claude、ChatGPT等）
|
| MCP（stdio）
|
bambu-cli-mcp cad-geometry-mcp
├─ BambuStudio CLI ├─ manifold-3d（WASM）
│ 适配器（execa） ├─ 二进制STL输入/输出
├─ 11个工具 ├─ 7个核心 + 4个工作流工具
├─ Zod模式 ├─ 连接器引擎
└─ 工作区管理器 └─ CAD引擎检测
| |
v v
BambuStudio CLI 进程内WASM
（定向，切片， （无Python，无子进程）
导出3MF）
```
**关键设计决策：
- **pnpm** 单体仓库，包含两个逻辑服务器
- **manifold-3d WASM** 用于几何运算 - 单一语言，无Python依赖
- **递归分割** - 将超大零件递归分割直到适合构建体积
- **表面验证的连接器** - 球体交叉探针过滤空位中的位置
- **每个零件一个3MF** - BambuStudio CLI堆叠对象；单独导出避免此问题
参见 [架构决策记录](docs/adr/) 获取完整理由。
## 开发
```bash
pnpm test # 29个测试，跨7个文件
pnpm build # TypeScript编译
pnpm run lint # 类型检查（tsc --noEmit）
pnpm run dev # 监视模式
```
### 项目结构
```
src/
index.ts # 入口点（--server标志）
bambu-cli-mcp/ # BambuStudio CLI包装器
server.ts, tools/, adapters/, schemas/
cad-geometry-mcp/ # 几何引擎
server.ts, tools/, engines/, schemas/
shared/ # 工作区、错误、类型
test/ # 7个测试文件，29个测试
docs/adr/ # 6个架构决策记录
examples/ # 工作流JSON示例
profiles/ # 打印机/工艺/耗材配置文件
```
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `BAMBU_STUDIO_PATH` | BambuStudio二进制文件路径 | 自动检测 |
## 已测试
- BambuStudio v02.06.01.55
- Node.js v22+ / v24
- macOS（ARM64）
- Bambu Lab X1E, P2S 打印机
## 许可证
MIT
