Bambu Lab Printer (LAN)

mcp-server-for-bambu

询问 Claude（或 Cursor、VS Code）你的 Bambu Lab 打印机正在做什么，并通过局域网让它暂停、预热或记录维护信息，无需连接云端。

适用于 Bambu Lab 3D 打印机的 MCP 服务。它通过打印机的本地 MQTT 接口直接与其通信。基于 P1S 构建并测试；其他支持 MQTT 的型号（P1P、X1C、A1）应该也能使用。

⚠️ 非官方项目——与 Bambu Lab 无关联

这是一个由社区构建的项目。它与 Bambu Lab / Shenzhen Tuozhu Technology Co., Ltd. 无关联，也未获其认可或赞助。“Bambu Lab”“Bambu Studio”“P1S”“P1P”“X1C”和“AMS”均为其各自所有者的商标；本项目仅为兼容性目的引用这些名称（描述性使用，属于合理使用）。本项目按“现状”提供，不附带任何保证。

演示

使用内置打印机模拟器（npm run sim）运行的实际工具调用及输出。使用 scripts/demo/ 重新生成；docs/demo-script.md 介绍如何录制与真实打印机的会话。

功能

实时状态	状态、当前阶段、进度、层数、剩余时间、喷嘴／热床／腔室温度、Wi-Fi 信号
AMS	每个槽位的耗材类型、品牌、颜色和剩余百分比，以及当前使用的槽位
健康状况	解码活动 HMS 警告，显示模块和严重程度，并附上各自的 Bambu wiki 链接
控制	暂停、恢复、取消、腔室灯、速度配置、预热、切换 AMS 槽位、原始 G-code
维护记录	在本地统计打印小时数，并提醒你何时需要维护导轨、碳杆或热端
引导式设置	无需编辑配置：告诉 Claude 你的 IP、序列号和访问码；保存前会先进行测试
安全性	取消、G-code 和切换 AMS 槽位均需明确确认；只读模式；仅限局域网地址
适用于所有支持 MCP 的环境	Claude Code 插件、Claude Desktop、Cursor、VS Code，以及任何使用 stdio 的 MCP 客户端
打印机模拟器	运行 npm run sim 即可启动虚拟打印机，用于试用、演示和测试

快速开始

你需要 Node.js 20+，并确保打印机已接入同一网络且已开启 LAN Mode Liveview。

Claude Code

安装插件（MCP 服务以及一段用于教 Claude 遵守确认规则的简短技能说明）：

/plugin marketplace add b84330808/mcp-server-for-bambu
/plugin install bambu-printer@mcp-server-for-bambu

或者只添加 MCP 服务：

claude mcp add --transport stdio --scope user bambu -- npx -y mcp-server-for-bambu

Claude Desktop

打开设置 → 开发者 → 编辑配置（Windows 系统上的 %APPDATA%\Claude\claude_desktop_config.json，macOS 系统上的 ~/Library/Application Support/Claude/claude_desktop_config.json），并添加：

{
  "mcpServers": {
    "bambu": {
      "command": "npx",
      "args": ["-y", "mcp-server-for-bambu"]
    }
  }
}

完全退出 Claude Desktop（托盘图标 → 退出）并重新打开。

Cursor

或者将以下内容放入 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "bambu": {
      "command": "npx",
      "args": ["-y", "mcp-server-for-bambu"]
    }
  }
}

VS Code

code --add-mcp "{\"name\":\"bambu\",\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"mcp-server-for-bambu\"]}"

或者将其添加到 .vscode/mcp.json。此版本通过环境变量传递凭据，并将访问码作为隐藏输入进行询问：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bambu-access-code",
      "description": "Bambu LAN access code (Settings > WLAN > LAN Mode Liveview)",
      "password": true
    }
  ],
  "servers": {
    "bambu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-for-bambu"],
      "env": {
        "BAMBU_IP": "192.168.1.50",
        "BAMBU_SERIAL": "01P00A1234567890",
        "BAMBU_ACCESS_CODE": "${input:bambu-access-code}"
      }
    }
  }
}

以上配置均位于 examples/ 中。

连接打印机

首次启动时，服务处于设置模式，并提供一个工具 setup_printer。从打印机的触摸屏读取以下三个值：

• IP：Settings → WLAN → 点击已连接的网络
• 序列号：Settings → Device → Device Info（P1S：01P00A…）
• 访问代码：Settings → WLAN → LAN Mode Liveview，共 8 个字符，不是 Wi-Fi 密码。必须开启 LAN Mode Liveview。

然后告诉你的助手：

“设置我的 Bambu 打印机。IP 是 192.168.1.50，序列号是 01P00A1234567890，访问代码是 12345678。”

setup_printer 会检查格式、连接打印机，并且仅在连接成功时保存凭据。重启一次服务（Claude Desktop：退出并重新打开；Claude Code：/mcp → 重新连接 bambu），打印机工具就会出现。

你也可以跳过此步骤，改为像 VS Code 示例中那样传入 BAMBU_IP、BAMBU_SERIAL 和 BAMBU_ACCESS_CODE 环境变量。

试试看

• “我的打印机现在在做什么？”
• “AMS 的 2 号槽位里装的是什么耗材？”
• “有 HMS 警告吗？”
• “打印机有哪些维护项目逾期了？”
• “暂停打印。” / “恢复。”
• “将喷嘴预热到 210，热床预热到 60。”
• “取消这次打印。”（会先询问你是否确认）
• “我刚给导轨上了润滑油，记录一下。”

工具

工具	功能	是否先询问？
get_status	状态、阶段、温度、进度、层数、HMS 警告、Wi-Fi
get_ams_info	各槽位的耗材类型 / 颜色 / 剩余百分比、当前使用的槽位
list_active_warnings	当前 HMS 警告及指向 Bambu 维基的链接
get_maintenance_status	打印时长以及润滑 / 清洁 / 检查警告
forecast_maintenance	根据近期打印频率预测各项维护任务的到期时间
get_recent_prints	最近 N 次打印记录：名称、时长、结束时间
mark_maintenance_done	记录维护任务（可通过 hours_ago 设置为过去的时间）
pause_print / resume_print	暂停并恢复当前打印
set_light	打开 / 关闭腔室灯
set_speed	静音 / 标准 / 运动 / 疾速
preheat	设置喷嘴和 / 或热床的目标温度
stop_print	取消打印。无法撤销	是（confirm: true）
run_gcode	发送原始 G-code（归位、Z 轴移动、手动卸料……）	是（confirm: true）
change_active_tray	将 AMS 切换到另一个槽位	是（confirm: true）

每个工具还带有 MCP 注解（readOnlyHint、destructiveHint），因此，对于会在运行工具前询问的客户端，可以区别对待读取工具和具有破坏性的工具。

安全性

此服务可以移动加热的工具头，也可以取消持续数小时的打印任务。它的设计旨在防止意外执行此类操作：

• 破坏性工具需要确认。 stop_print、run_gcode 和 change_active_tray 必须在调用时传入 confirm: true 才会执行，其描述会提示模型仅在你明确同意后才设置该参数。请同时保留客户端自身的工具审批提示，作为第二道检查。
• 只读模式。 设置 BAMBU_READ_ONLY=1 后，服务只会注册读取工具。无法暂停、取消、加热或移动打印机。对于共用设备或演示，这是一个不错的默认设置。
• 仅限局域网。 服务只会连接到你配置的那台打印机 IP，使用端口 8883，不会连接其他地址：不连接 Bambu 云端，也不收集遥测数据。setup_printer 会拒绝私有地址范围之外的地址（192.168.x.x、10.x.x.x、172.16–31.x.x，以及链路本地、环回和 Tailscale 使用的 100.64/10 范围）。切勿将打印机的 MQTT 端口转发到互联网。
• 使用可信网络。 打印机使用自签名证书，因此连接经过加密，但不会验证打印机身份。请在可信网络中使用。
• 加热器会保持开启。 preheat 和 M104/M140 会让加热器持续保持在目标温度，直到有其他操作更改设置。离开前请关闭加热器（设为 0）。
• 凭据保存在本地。 凭据存储在你的用户配置目录中（见下文）；在 macOS 和 Linux 上仅文件所有者有权限访问。

配置

环境变量	默认值	含义
BAMBU_IP、BAMBU_SERIAL、BAMBU_ACCESS_CODE	来自已保存的 .env	打印机凭据。环境变量优先于已保存的文件
BAMBU_READ_ONLY	0	设为 1 时只注册读取工具
BAMBU_CONFIG_DIR	见下文	.env 和维护记录文件的存放位置
MAINTENANCE_LEDGER_PATH	<config dir>/maintenance.json	记录文件位置

配置目录为：

• Windows：%APPDATA%\mcp-server-for-bambu\
• macOS：~/Library/Application Support/mcp-server-for-bambu/
• Linux：~/.config/mcp-server-for-bambu/（或 $XDG_CONFIG_HOME）

0.2.0 及更早版本会将 .env 和 maintenance.json 保存在安装包内，npx 更新可能会删除这些文件。0.3.0 仍会读取旧位置的 .env，并在首次启动时将旧记录文件复制到配置目录。

记录会持久化到本地 JSON 文件，即使发生崩溃也不会丢失（活动会话每经过 5 分钟就会保存检查点）。阈值定义在 src/types.ts 中：

任务	间隔
清洁碳纤维杆	100 打印小时
润滑直线导轨	200 打印小时
检查热端／喷嘴磨损情况	500 打印小时

距达到阈值不到 10 小时时，任务状态会变为 DUE_SOON（🔔）；超过阈值后则变为 OVERDUE（⚠️）。

无需打印机即可试用

克隆仓库并运行 npm install 后，执行 npm run sim，即可启动一台正在打印 Benchy、进度过半的模拟 P1S，配有 4 槽 AMS，运行于 mqtts://127.0.0.1:8883。它会响应状态请求，并执行暂停、恢复、取消、速度、预热、灯光和 AMS 命令。将服务指向它：

BAMBU_IP=127.0.0.1 BAMBU_SERIAL=01P00ASIMULATOR BAMBU_ACCESS_CODE=12345678 node dist/index.js

设置 SIM_PORT 可使用其他端口，然后将相同值传给 BAMBU_MQTT_PORT。测试套件也使用同一个模拟器。

开发

git clone https://github.com/b84330808/mcp-server-for-bambu.git
cd mcp-server-for-bambu
npm install
npm test             # builds, then runs unit + end-to-end tests against the simulator
npm run dev          # tsc --watch
npm run sim          # simulated printer

若要从 MCP 客户端运行本地构建，请将其指向 node /absolute/path/to/mcp-server-for-bambu/dist/index.js。

src/
  index.ts          MCP server bootstrap + tool definitions
  config.ts         Env / .env loading, LAN address check
  paths.ts          Per-user config directory
  mqtt-client.ts    TLS MQTT client for the printer (port 8883, self-signed cert)
  setup.ts          setup_printer: validate, test the connection, save
  maintenance.ts    Print-time ledger with crash-safe atomic writes + recovery
  hms.ts            Bambu HMS error code → human label
  stages.ts         Stage / speed / tray code → human label
  commands.ts       MQTT command payloads
sim/printer.mjs     Simulated printer (aedes broker over TLS)
plugins/            Claude Code plugin; .claude-plugin/marketplace.json lists it
server.json         MCP Registry metadata

协议说明：

• 订阅：device/{serial}/report
• 发布：device/{serial}/request，内容为 {"pushing":{"sequence_id":"...","command":"pushall"}}
• 身份验证：用户名为 bblp，密码为访问码；每次连接使用随机客户端 ID（复用 ID 会导致两个客户端互相断开）
• 证书为自签名证书 → rejectUnauthorized: false

许可证

MIT