内容
# bambu-mcp
使用 **Bambu Lab 打印机**（P2S / P1S / X1 系列）在 **局域网模式**下通过 AI 代理（如 Claude Code、Claude Desktop 或任何 MCP 客户端）驱动打印机。支持切片、上传、打印和通过 MQTT + FTPS 监控。
基于 [`bambu-js`](https://www.npmjs.com/package/bambu-js) 构建（MQTT 控制 + 遥测，FTPS 文件传输）。官方没有提供 Bambu MCP —— 这是社区工具，与 Home Assistant / OrcaSlicer 使用的本地 API 相同。
## 安装
```bash
npm install -g bambu-mcp # 或：npx bambu-mcp
```
## 打印机设置（一次性）
在打印机屏幕上：**设置 → 局域网模式 → 启用**。记下 **IP 地址**、**访问代码** 和 **序列号**。
## 配置 — 通过环境变量设置密钥，不要在命令行中设置
```bash
export BAMBU_IP=192.168.1.42
export BAMBU_ACCESS_CODE=xxxxxxxx
export BAMBU_SERIAL=01P00A1234567890
export BAMBU_MODEL=P1S # P1S | H2D（不区分大小写）— P2S 使用 P1S 协议
```
## 在 Claude Code 中注册
```bash
claude mcp add bambu -- \
env BAMBU_IP=$BAMBU_IP BAMBU_ACCESS_CODE=$BAMBU_ACCESS_CODE \
BAMBU_SERIAL=$BAMBU_SERIAL BAMBU_MODEL=$BAMBU_MODEL \
npx bambu-mcp
```
或在 `~/.claude.json` / Claude Desktop 配置中：
```json
{
"mcpServers": {
"bambu": {
"command": "npx",
"args": ["bambu-mcp"],
"env": {
"BAMBU_IP": "192.168.1.42",
"BAMBU_ACCESS_CODE": "xxxxxxxx",
"BAMBU_SERIAL": "01P00A1234567890",
"BAMBU_MODEL": "P1S"
}
}
}
}
```
## 工具
| 工具 | 类型 | 功能 |
|------|------|------|
| `bambu_slice` | 本地 | STL/STEP/3MF → 可打印的 .3mf（OrcaSlicer/Bambu Studio CLI） |
| `bambu_status` | 读取 | gcode 状态、进度 %、剩余分钟、层、作业名称 |
| `bambu_temps` | 读取 | 喷嘴 / 平台 / 室温（当前 + 目标） |
| `bambu_ams` | 读取 | AMS 单位 + 每槽丝材类型、颜色、喷嘴范围、活动槽 |
| `bambu_hms` | 读取 | 活动健康管理系统的故障，解码为消息 |
| `bambu_list_files` | 读取 | 打印机 FTPS 存储上的文件 |
| `bambu_upload` | 写入 | 通过 FTPS 上传切片文件 |
| `bambu_print_file` | 写入 | 在打印机上启动打印文件 |
| `bambu_pause` / `bambu_resume` / `bambu_stop` | 写入 | 打印控制 |
| `bambu_gcode` | 写入 | 运行任意原始 G-code 命令（通用逃脱口） |
| `bambu_set_temps` | 写入 | 设置喷嘴 / 平台目标温度 |
| `bambu_home` | 写入 | 所有轴归位（G28） |
| `bambu_set_speed` | 写入 | 速度配置文件 1-4（静音/标准/快速/疯狂） |
| `bambu_light` | 写入 | 室灯开启 / 关闭 / 闪烁 |
| `bambu_snapshot` | 相机 | 捕获 JPEG 图片到磁盘（参见注意事项） |
| `bambu_download_file` | 文件 | 从打印机下载文件 |
| `bambu_delete_file` | 文件 | 删除打印机上的文件（永久） |
`bambu_print_file` 接受可选的 `amsMapping` 参数 — 将每个板上的丝材映射到 0 基数的 AMS 槽（例如 `[2]` 从槽 2 打印，`[0,3]` 将丝材 1 映射到槽 0，将丝材 2 映射到槽 3）。使用 `bambu_ams` 读取当前槽位。
## 典型 AI 工作流程
```
生成/选择 STL
→ bambu_slice(inputPath, settings="printer.json;process.json") → out.3mf
→ bambu_upload(out.3mf)
→ bambu_print_file(remoteName)
→ 轮询 bambu_status
```
## 切片
`bambu_slice` 封装了 OrcaSlicer / Bambu Studio CLI（共享 PrusaSlicer 分叉标志）。二进制文件自动检测（`orca-slicer` 在 PATH 中，或 `~/Applications/{OrcaSlicer,BambuStudio}.AppImage`）；使用 `SLICER_BIN` 覆盖。
**裸 STL** 需要预设 — 从切片器导出一次预设（导出 → 导出配置 → 打印机 + 过程 JSON），并通过 `settings` 以分号分隔传递。一个 **项目 `.3mf`** 已经嵌入了预设，因此可以省略 `settings`。
## 注意事项
- **P2S 架构**：`bambu-js` 提供了 `P1S` / `H2D` 的类型化架构。P2S 使用 P1S 家族的 MQTT 协议 — **已验证**：`bambu_status` / `bambu_temps` / `bambu_list_files` 在 `BAMBU_MODEL=P1S` 的真实 P2S 上有效。打印命令作为原始负载发送；`project_file` 启动打印负载是社区局域网格式，尚未在 P2S 上确认 — 在依赖无人值守打印之前请先验证。
- **相机**：`bambu_snapshot` 使用 P1S TCP-JPEG 协议。在 P1S/H2D 上有效，但在 P2S 上返回“无效 JPEG 数据”（不同的相机协议）— 目前将 P2S 相机捕获视为不支持。
- **`bambu_gcode` / `bambu_home` / `bambu_set_temps`** 直接发送命令；在打印过程中不要运行运动或归位命令。`bambu_gcode` 是一个无防护的逃脱口 — 它将运行您给定的任意 G-code 命令。
- 仅限局域网模式。无云账户路径（保持本地 + 轻量级认证）。
- `bambu_status` / `bambu_temps` 强制一次完整的 MQTT `pushall`，然后读取最新的缓存报告（≤3 秒等待）。
## 开发
```bash
npm install
npm run build # tsc → dist/ (ESM)
npm test # vitest
```
## 许可证
MIT
