Bambu Printer MCP

STL 操作工具

所有 STL 工具都会将完整网格几何体载入内存。对于大于 10 MB 的文件，请监控内存用量，并优先使用较小的文件进行测试。

get_stl_info

检查 STL 文件但不做任何修改。返回边界框尺寸、面数、顶点数和模型中心。

{
  "stl_path": "/path/to/model.stl"
}

scale_stl

沿各个轴缩放 STL 模型。省略某个轴即可保持其不变（默认值为 1.0）。

{
  "stl_path": "/path/to/model.stl",
  "scale_x": 1.5,
  "scale_y": 1.5,
  "scale_z": 1.0
}

要进行均匀缩放，请将三个轴设置为相同的值：

{
  "stl_path": "/path/to/model.stl",
  "scale_x": 2.0,
  "scale_y": 2.0,
  "scale_z": 2.0
}

rotate_stl

围绕一个或多个轴旋转 STL 模型。角度以度为单位。省略的轴默认为 0。

{
  "stl_path": "/path/to/model.stl",
  "angle_x": 0,
  "angle_y": 0,
  "angle_z": 90
}

extend_stl_base

在模型下方添加实体几何体，以增加底座高度。适用于底部接触面积较小或不稳定的模型，可改善其在打印平台上的附着效果。

{
  "stl_path": "/path/to/model.stl",
  "extension_height": 3.0
}

extension_height 的单位为毫米。

合并距离小于指定容差的顶点。这可以填补网格中的小缝隙，并略微减小文件大小。适合作为切片前的清理步骤。

{
  "stl_path": "/path/to/model.stl",
  "tolerance": 0.01
}

tolerance 的单位为毫米，若省略，则默认为 0.01。

center_model

平移模型，使其包围盒的中心位于世界原点 (0, 0, 0)。适合在应用变换或导出到其他工具使用前执行。

{
  "stl_path": "/path/to/model.stl"
}

lay_flat

识别模型上最大的平坦表面，并旋转模型，使该表面朝下并位于 XY 平面（Z = 0）上。这是切片前常见的准备步骤，可尽量减少对支撑的需求。

{
  "stl_path": "/path/to/model.stl"
}

注意：此操作最适用于具有明显主导平面的模型。对于有机形状或圆润形状，结果可能难以预测。

打印机控制工具

所有打印机工具都接受可选参数 host、bambu_serial 和 bambu_token。若省略，则使用环境变量 PRINTER_HOST、BAMBU_SERIAL 和 BAMBU_TOKEN 的值。显式传入这些参数适用于同时使用多台打印机的情况。

服务还接受别名变量 BAMBU_PRINTER_HOST、BAMBU_PRINTER_SERIAL 和 BAMBU_PRINTER_ACCESS_TOKEN，以及 BAMBU_PRINTER_MODEL 和 BAMBU_STUDIO_PATH。

get_printer_status

获取打印机当前状态，包括温度、打印进度、层数、剩余时间和 AMS 槽位数据。内部会发送 push_all MQTT 命令，强制获取最新状态报告后再读取缓存状态。

{
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

腔室状态会从较新固件打包的 CTC 报告中解码当前温度，包括 P2S，同时保留旧版腔室／机架字段。

返回一个结构化对象，字段包括 status（gcode_state 字符串）、temperatures.nozzle、temperatures.bed、temperatures.chamber、print.progress、print.currentLayer、print.totalLayers、print.timeRemaining 和 ams（打印机返回的原始 AMS 数据）。

get_printer_filaments

读取实时 AMS 库存，并在已知 bambu_model 时，将每个已装入料盘映射到 Bambu Studio 耗材配置文件 JSON 路径。结果包含摘要、各槽位的显示标签、配置文件匹配置信度，以及适用于简单单材料命令行切片的建议 load_filaments 值。

{
  "bambu_model": "h2d",
  "nozzle_diameter": "0.4",
  "host": "192.168.1.100",
  "bambu_serial": "094...",
  "bambu_token": "your_access_token"
}

重要字段：

• summary.loaded_slots、summary.resolved_profile_slots、 summary.unresolved_loaded_slots、summary.empty_slots
• trays[].display_name、trays[].tray_color、trays[].remain_percent
• trays[].resolved_profile_path
• trays[].profile_resolution：exact-model-nozzle、model、generic 或 unresolved
• trays[].match_confidence：high、medium、low 或 none
• recommended.load_filaments：未提供显式耗材覆盖时，MCP 自动切片将使用的配置文件路径

list_printer_files

列出存储在打印机 SD 卡上的文件。扫描 cache/、timelapse/ 和 logs/ 目录，并同时返回平铺列表和按目录分组的明细。

这是只读查询：不会创建目录。成功列出根目录后，若发现可选目录不存在，则会返回空列表。身份验证、TLS、权限和传输失败会作为错误报告，而不会返回空结果或部分结果。

{
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

从打印机的舱内摄像头捕获单张 JPEG 图像。只读。

已接入两种传输方式，根据 bambu_model 选择：

• TCP-on-6000 适用于 A1、A1 mini、P1S、P1P。采用 OpenBambuAPI/video.md 中的原生协议：在端口 6000 上使用 TLS、80 字节认证数据包（bblp + 访问令牌），以及重复出现的 16 字节帧头 + JPEG 负载。打印机会先重放缓冲的最后一帧；在闲置一段时间后，这可能会显示很久以前的舱内画面，因此该工具会跳过这一帧并返回下一张实时画面（约 3 秒后）。如果在 timeout_ms 时间内没有后续实时画面，则会失败，而不会返回可能已过时的图像。
• RTSP 适用于 X1、X1 Carbon、X1E、P2S、X2D 和 H2、H2S、H2D、H2C、H2D Pro。通过命令行调用 ffmpeg：rtsps://bblp:<token>@<host>:322/streaming/live/1 -frames:v 1。OpenBambuAPI 的 video.md 中未记载 H2 系列，但其固件使用与 X1 相同的 RTSP 端点（已于 2026-04-27 在 H2S 上进行实时验证）。

{
  "save_path": "/tmp/snap.jpg",
  "timeout_ms": 8000,
  "bambu_model": "h2s",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

返回 { status, format: "image/jpeg", sizeBytes, base64, savedTo?, transport }。transport 为 "tcp-6000" 或 "rtsps-322"，调用方可据此判断帧是通过哪种方式获取的。传入 save_path 还可将字节写入磁盘；否则只返回 base64 负载。

delete_printer_file

通过 FTPS 从打印机的 SD 卡中删除单个文件。**具有破坏性。**需要 confirm: true——否则调用会返回 status: "skipped"，且不会联系打印机。路径中不允许包含路径遍历片段（..）。只能删除 cache/、timelapse/ 和 logs/ 目录下的文件。

{
  "filename": "old_print.gcode.3mf",
  "confirm": true,
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

如果只提供文件名，默认路径为 cache/<filename>。如需指定其他目录，请传入相对路径：

{ "filename": "timelapse/2026-04-26_12-00.mp4", "confirm": true }

{ "filename": "logs/printer.log", "confirm": true }

upload_gcode

将字符串中的 G-code 内容直接写入打印机的 cache/ 目录。内容会先写入临时文件，再通过 FTPS 上传。

{
  "filename": "calibration.gcode",
  "gcode": "G28\nM104 S210\nG1 X100 Y100 Z10 F3000\n",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

upload_file

将本地文件（G-code 或 3MF）上传到打印机。如果 print 为 true，且文件为 .gcode 文件，则上传成功后会自动调用 start_print_job。对于 .3mf 文件，上传会正常完成，但必须使用 print_3mf 开始打印（该工具会处理打印板选择和元数据）。

{
  "file_path": "/Users/yourname/Downloads/part.3mf",
  "filename": "part.3mf",
  "print": false,
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

start_print_job

开始打印已存储在打印机 SD 卡上的 .gcode 文件。不要用于 .3mf 文件——请改用 print_3mf，它会通过包含正确元数据的 project_file MQTT 命令进行处理。

{
  "filename": "cache/calibration.gcode",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

如果 filename 不包含目录前缀，服务端会自动添加 cache/。

cancel_print

取消当前正在运行的打印任务。发送 state: "stop" 的 UpdateState MQTT 命令。无法恢复——如果可能还要继续打印，请使用 pause_print。

{
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

pause_print

暂停当前正在运行的打印任务。发送 state: "pause" 的 UpdateState MQTT 命令。可通过 resume_print 恢复。

{
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

resume_print

恢复已暂停的打印任务。发送 state: "resume" 的 UpdateState MQTT 命令。

{
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

clear_hms_errors

清除打印机上的 HMS 或打印错误状态。发送 Bambu 的 clean_print_error MQTT 命令。

{
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

set_print_speed

设置当前打印速度模式。接受的 mode 值为 silent、standard、sport、ludicrous，或对应的数字 1、2、3 和 4。

{
  "mode": "sport",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

set_airduct_mode

将 H2/P2 风道模式设为 cooling 或 heating。此功能仅适用于受支持的打印机。

{
  "mode": "cooling",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

reread_ams_rfid

触发 Bambu AMS 的 RFID 重读，适用于一个 AMS 槽位。这可能会移动 AMS 耗材；仅在打印机空闲且未装载耗材时使用。

{
  "ams_id": 0,
  "slot_id": 1,
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

set_temperature

通过 MQTT 为热床或喷嘴设置经过检查的目标温度。设置正温度需要提供打印机型号和最新且匹配的打印机遥测数据；加热喷嘴还需要声明已装载的 material 和匹配的 nozzle_diameter（默认值为 0.4）。型号／组件和材料分别有各自的温度上限。将目标温度设为 0 可关闭加热器，无需提供材料或喷嘴元数据。可接受的 component 值为 bed、nozzle、extruder、tool 和 tool0。

手动加热喷嘴时会检查当前报告的 AMS 托盘或外置料盘。对于多喷嘴打印机，如果当前喷嘴／材料选择不明确，则会拒绝操作；此时请使用经过检查的切片任务或打印机自身的控件。停止和关闭加热器的命令会取消待处理的服务端打印／加热操作。通过 MCP 恢复打印时，必须是同一服务实例检查并启动的同一个已暂停任务，且遥测数据必须是最新且匹配的；其他已暂停任务仍可通过打印机控制。

{
  "component": "nozzle",
  "temperature": 220,
  "bambu_model": "p1s",
  "material": "PLA",
  "nozzle_diameter": 0.4,
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

set_fan_speed

将打印机风扇速度设为 0 至 100%。可接受的 fan 值为 part、auxiliary、chamber、1、2 和 3。

{
  "fan": "chamber",
  "speed": 40,
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

set_light

设置打印机灯光节点模式。常见的 Bambu 固件会将仓室灯报告为 chamber_light；有效模式为 on、off 和 flashing。

{
  "light": "chamber_light",
  "mode": "on",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

skip_objects

在正在进行的多对象打印过程中跳过指定的对象 ID。请先对切片后的 3MF 使用 list_3mf_plate_objects 查找 ID。

{
  "object_ids": [6495, 6496],
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

set_ams_drying

在带加热功能的 AMS 设备（AMS Pro / AMS-HT）上启动或停止 AMS 耗材干燥周期。action 参数接受 start 或 stop。ams_id 必须是 0 到 3 之间的整数。

{
  "action": "start",
  "ams_id": 0,
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token"
}

停止干燥：

{
  "action": "stop",
  "ams_id": 0
}

inspect_print_file

在决定导出或打印前，离线检查已准备好的切片 3MF 或文本 G-code 文件。此工具会将文件复制到私有只读快照中，并复用打印预检所用的相同归档、选定平台、型号／喷嘴／材料及温度检查。它不会联系打印机，也不会自动切片未切片的项目。

{
  "file_path": "/path/to/bracket.gcode.3mf",
  "bambu_model": "p1s",
  "plate_index": 0,
  "nozzle_diameters": [0.4],
  "bed_type": "textured_plate"
}

必须提供 file_path 和明确的 bambu_model；绝不会从配置中推断型号。plate_index 从 0 开始，默认值为 0。喷嘴／热床检查是与文件声明进行的可选比对，不代表对已安装硬件的观测。此工具仅接受这五个参数名称；凭据、主机和可执行文件／桥接覆盖参数均不适用于此工具。

通用结果包含 receipt_version: "1"、evidence: "file-only"、dispatch_authorized: false、artifact（sha256、byte_length、file_format）、请求的 selection，以及原始 inspection，其中包括声明的型号、喷嘴、材料／已使用的耗材位置、内部平台路径和经过检查的温度峰值。哈希值和字节长度用于标识所检查的确切快照；使用方必须将它们与自身的制品和选定平台进行比对。临时快照会被删除，其路径不具备调度权限。回执无法证明打印机已就绪、实体材料／喷嘴的实际内容、适配性、完整运动模拟结果或打印权限。实际打印路由仍会独立检查已调度的快照，并要求最新的硬件状态和人工预检。

print_3mf

用于启动 Bambu 打印的主要工具。建议输入：从 FULU OrcaSlicer-bambulab、OrcaSlicer 或 Bambu Studio 导出的预切片 .gcode.3mf——参见切片指南。此工具会处理完整工作流：

1. 检查 3MF 是否包含嵌入的 G-code（Metadata/plate_<n>.gcode 条目）。
2. 如果未找到 G-code，则尝试通过已配置的切片器自动切片。配置文件准备或切片失败时，会在上传前停止操作。有关经过测试的 CLI 版本和组合，请参阅切片指南。
3. 解析切片后的 3MF，以提取正确的打印板文件并计算其 MD5 哈希值。
4. 读取切片器元数据和任何显式的 AMS 选择，以构建耗材映射。
5. 使用 basic-ftp 上传到对应机型的位置：H2/全尺寸 A1 上传到 SD 卡根目录；P1/X1/A1 mini/P2S 上传到 cache/。X2D 的 print_3mf 则会在 macOS 或 Linux 上使用经过检查的原生路径，将任务存储到已就绪的 SD 卡或 USB 盘上；否则存储到内部存储（eMMC）。
6. 为目标打印机系列发送正确的 MQTT 打印命令。对于 H2S/H2D/H2C，这意味着使用 project_file，并设置项目长度的 ams_mapping、并行的 ams_mapping2 和兼容 H2 的校准标志。

{
  "three_mf_path": "/Users/yourname/Downloads/bracket.3mf",
  "bambu_model": "p1s",
  "bed_type": "textured_plate",
  "host": "192.168.1.100",
  "bambu_serial": "01P00A123456789",
  "bambu_token": "your_access_token",
  "bed_leveling": true,
  "flow_calibration": true,
  "vibration_calibration": true,
  "timelapse": false,
  "use_ams": true,
  "ams_mapping": [0, 1]
}

bambu_model 是机型专属路由和预设选择的必填项。它本身不会验证预切片的 G-code。使用 BambuStudio、FULU 和 Orca CLI 进行准备时，还必须提供与机型和喷嘴完全匹配的机器预设，并且会拒绝不完整的配置文件。使用错误的机型可能损坏硬件。如果工具调用中未提供 bambu_model，且环境中也未设置 BAMBU_MODEL，服务器会通过 MCP elicitation 交互询问（如果客户端支持），否则返回明确的错误。

如果省略 bed_type，则默认为 textured_plate。nozzle_type（stainless_steel、hardened_steel、tungsten_carbide、brass；默认值为 BAMBU_NOZZLE_TYPE）用于在项目必须自动切片时设置已安装的喷嘴；任务的喷嘴类型必须与打印机报告的类型一致，且 P1S/P1P/A1 的标准预设假定使用不锈钢喷嘴。nozzle_volume_type（standard、high_flow；默认值为 BAMBU_NOZZLE_VOLUME_TYPE）同样用于在自动切片时设置已安装喷嘴的流量类型；它必须与打印机报告的喷嘴流量一致。发送 MQTT 打印命令后，服务器会监听打印机主动推送的报告，最长 15 秒（BAMBU_DISPATCH_CHECK_MS），并返回 dispatch: "started" 或 "unconfirmed"；如果固件 01.08.05+ 拒绝命令（HMS 0500-0500-0001-0007，需要启用 LAN Only Mode 和 Developer Mode），则调用会失败并说明原因；再次打印前，请先使用 clear_hms_errors 清除这条致命 HMS 条目。ams_slots 是首选的覆盖输入；ams_mapping 仍可作为原始的备用入口。对于配备 AMS 的 H2 打印机，如果切片文件声明了耗材，即使 use_ams: false 也不会跳过映射查询。如果 H2 的预切片任务声明了耗材但未提供映射，服务器会在发送前失败；请传入显式的 ams_slots、原始 ams_mapping 或 auto_match_ams: true。

设置 auto_match_ams: true，即可将切片后 3MF 中的 tray_info_idx 值与实时 AMS 库存匹配，并使用匹配到的 ams_slots。匹配器会根据 (tray_info_idx, tray_color) 进行关联，并跟踪已分配的插槽，因此，即使打印任务中的两种耗材具有相同的 SKU 但颜色不同（例如，黑色和白色的两卷 GFG02 PETG HF），也能正确匹配。如果 3MF 中的耗材未设置颜色，或者只装载了一卷该 SKU 的耗材，则会退回到仅按 SKU 匹配。如果无法解析某种耗材，则会返回结构化的 missing 报告（reason: "no_loaded_match" | "color_mismatch" | "exhausted" | "no_sku"）。如果显式提供了 ams_slots 或 ams_mapping，则忽略此设置。

此工具无法覆盖层高、喷嘴温度和其他切片器参数——这些参数会在切片时写入 3MF 的 G-code 中。请在生成 3MF 前于切片器中应用这些设置。 对于可选的 FULU 桥接，将 connection_mode: "bambu_network" 设为必需，并明确选择 connection_type: "cloud" 或 "lan"；请参阅 FULU 设置。命令提交成功并不代表打印机已接受命令：请检查打印机状态、HMS 错误以及打印机本身。

bambu_network_bridge_status

使用 {} 检查已配置的 FULU 桥接，而不启动它。使用 {"connect": true} 启动主机、完成握手并初始化 Agent。有关如何解读结果，请参阅桥接探测。

bambu_network_call

调用允许的只读探测，例如 {"method": "net.is_user_login", "payload": {}}。默认会注入已初始化的 Agent；对于 bridge.handshake，请使用 with_agent: false。原始打印机修改操作和未知方法会被拒绝；请使用专用且经过检查的打印或打印机工具。

X2D 原生传输（macOS）

安装 Bambu Studio 及其网络插件，并安装 Apple 命令行开发者工具（clang++）。插件会在运行时加载，不会随软件包一起分发。在已安装的 bambu-printer-mcp 软件包目录中运行 npm run build:native。如果是全局安装，可通过 npm root -g 查找该目录；如果是解压后的桌面扩展，则在扩展目录中运行同一命令。更新软件包后请重新构建。Linux 请参阅 X2D 原生传输（Linux）；Windows 只能使用状态查询和切片功能。

npm 软件包和桌面应用捆绑包包含 native/bambu-native-print.cpp、scripts/build-bambu-native.sh 和 Linux 安装脚本，但不包含开发者编译的二进制文件。无论启动目录为何，服务都会相对于已安装的软件包查找构建好的辅助程序。受信任的服务设置 BAMBU_NATIVE_HELPER 可指定备用可执行文件。

对于 X2D，print_3mf 默认使用 connection_mode: "bambu_native"；旧版 lan_mqtt_ftps 请求会重定向至该模式。请提供 ams_slots、完整的项目级 ams_mapping，或设置 auto_match_ams: true。仅使用一个外置料盘的任务必须明确设置 use_ams: false；同时使用 AMS 托盘和外置料盘的任务会将外置料盘映射为 254（左侧／副喷嘴）和 255（右侧／主喷嘴）。原始 ams_mapping2 和喷嘴／额外选项覆盖项会在分发前被拒绝；服务会根据经过校验的结构化映射生成两种 AMS 表示形式。模型／喷嘴／材料检查、最新的打印机状态检查和人工预检，会在辅助程序收到私有快照前执行。原生辅助程序会在每次提交打印前（包括证书重试时），以及执行经过校验的加热、恢复或清除错误命令前，请求最新的共享打印机状态授权；自定义辅助程序必须支持此握手。无需预检也可使用停止和关闭加热器功能。原生仅上传请求会执行与 FTPS 上传相同的所有平台检查。此类请求接受 project_name、preset_name、bed_type 和现有的 plate_index；AMS、喷嘴和校准打印选项会被拒绝。请使用 print_3mf 设置经过校验的打印选项。

辅助程序会等待连接／证书交换，并且只会对初始的 -4030 发送进行一次重试。升级后请重新构建辅助程序，以获取修复了清理问题的版本。成功提交的回执会使辅助程序在插件清理可能将已接受的任务变成错误之前退出。如果旧版／自定义辅助程序在提交后崩溃，服务会报告状态不确定：重试前请检查打印机状态和任务名称，因为重新发送可能导致重复打印。此前的硬件测试已在 X2D 上达到 RUNNING 状态；此修订版通过模拟传输回归测试和全新安装验证，但未进行新的实体打印。bambu_connect 是 macOS 上的可选交接功能，可供用户在 Bambu Connect 中检查，不会启动打印。原生任务、加热器和错误控制仍执行通用安全检查；原始控制无法绕过这些检查。请求取消、停止和关闭加热器操作会中断待处理的原生辅助程序；服务会等待进程退出后再释放经过校验的文件。已经发送给打印机的命令无法通过取消请求撤回，因此重试前请确认打印机状态。

X2D 原生传输（Linux）

在 x86-64 Linux 上，只需运行一条命令即可构建辅助程序，并安装 Bambu 的网络插件和 Bambu Studio 证书。需要 C++ 编译器（g++ 或 clang++）和网络连接；不需要桌面环境或切片软件：

npx -y -p bambu-printer-mcp bambu-printer-mcp-native-setup

请使用与服务端相同的软件包版本，例如 [email protected]；如果缺少安装或安装已过期，服务端错误会给出准确命令。此设置会下载 Bambu Studio 自行安装的 Linux 插件，该插件固定为确切版本和 SHA-256 校验值，并与证书一起存储在 ~/.config/bambu-printer-mcp/bambu-native 下（可通过 BAMBU_NATIVE_HOME 或 XDG_CONFIG_HOME 更改位置；服务端也必须设置相同的值）。此软件包不会重新分发该插件，也绝不会使用 Bambu Studio 自行自动更新的副本。服务端会自动找到此安装，并将插件和证书路径传给辅助程序。升级后，请使用服务端对应的软件包版本重新运行设置：服务端会拒绝使用其他版本构建的辅助程序。只有缺失或已更改的文件才会重新下载。随后，设置会离线加载一次插件，以便在安装期间报告缺失的系统库，而不是等到执行停止命令时才报告。--verify 会在不联网的情况下重复这些检查。在 Linux 上，服务端只使用此托管辅助程序或 BAMBU_NATIVE_HELPER；不会使用软件包本地的 npm run build:native 二进制文件。

--check-update 会向 Bambu 的插件服务查询最新的 Linux 插件，并将对应 Bambu Studio 头文件中的 PrintParams 布局与辅助程序进行比较。此命令只报告结果：设置绝不会安装未固定版本的插件，因为布局更改会导致打印参数错误。只有检查通过并完成硬件测试后，软件包发布版本才会更新固定版本。

安装好辅助程序、插件和证书后，X2D 打印、上传和控制会使用与上述 macOS 部分相同的路由、安全检查和授权握手。在 Linux 上，停止和关闭加热器命令会同时通过原生路由和 MQTT 发送，因此辅助程序卡住也不会延误这些命令。等该打印机的所有较早打印或加热辅助程序退出，且即时 MQTT 尝试结束后，系统会再次通过 MQTT 发送命令，以确保它们都无法在此之后发送命令；只要原生路由或后续 MQTT 发送任一成功，就视为成功，结果会在 routes 下列出所有发送操作。每次 MQTT 发送会在 15 秒后放弃（BAMBU_EMERGENCY_MQTT_TIMEOUT_MS），因此无法连接 MQTT 不会阻止原生路由已发送的停止命令。截止时间之后完成的连接无法发送已过期的命令；系统会通过强制关闭并使该客户端失效来丢弃已经排队的 MQTT 发布。重复发送停止或关闭加热器命令不会造成问题。macOS 仍只使用原生路由。在这两个系统上，如果打印机报告 SD 卡或 USB 闪存盘已就绪，打印任务会发送到该存储设备，以便从打印机重新打印，并由读取存储卡的工具归档；否则会发送到内部存储（eMMC），与 Bambu Studio 的“打印”按钮始终采用的方式相同。BAMBU_NATIVE_TRY_EMMC_PRINT=1（或 0）可强制选择存储方式。服务端只接受校验和与固定值匹配的插件；BAMBU_NATIVE_ALLOW_UNPINNED_PLUGIN=1 是可信覆盖选项，可自行承担风险，用于测试其他构建版本。如果安装不完整，Linux 会保留先前行为：X2D 状态查询和切片功能正常，停止、暂停和关闭加热器命令使用 MQTT，而原生打印请求会在联系打印机前显示设置命令。Bambu 只为 x86-64 发布 Linux 插件；其他架构仍使用 MQTT 行为。

x2d_native_control

此可选 X2D 元数据工具接受 ams_filament_setting 和 extrusion_cali_sel，以及只读查询 extrusion_cali_get、extrusion_cali_get_result 和 flowrate_get_result。它会验证命令字段、数值元数据以及 AMS 单元／料槽选择。原始 JSON 不开放运动控制、装载耗材、加热、安全设置更改和任务控制；如有可用的专用校验工具，请使用这些工具。声明元数据并不能验证线轴中的实际耗材。

print_3mf_bambu_network

通过 FULU 单独配置的联网运行时提交已切片项目。connection_type 默认为 cloud。云端和 LAN 桥接任务都需要打印机 IP、LAN 访问码、匹配的序列号／设备 ID，以及最新的 MQTT 安全遥测数据。文件、原始 AMS／喷嘴映射和额外选项的覆盖不能替代经过校验的参数。请参阅打印示例和 AMS 要求。桥接返回码为 0 表示已提交，不代表实际打印已开始，也不代表直接支持 X2D。

resolve_3mf_ams_slots

试运行 AMS 匹配，不上传文件或启动打印。该工具会读取 Metadata/plate_<n>.json 和 Metadata/slice_info.config，然后将必需的 tray_info_idx 值与实时 AMS 料槽进行比对。

{
  "three_mf_path": "/Users/yourname/Downloads/bracket.gcode.3mf",
  "bambu_model": "h2d",
  "host": "192.168.1.100",
  "bambu_serial": "094...",
  "bambu_token": "your_access_token"
}

list_3mf_plate_objects

列出已切片 3MF 构建板中的对象 ID。使用 skip_objects 前请先运行此工具，以便传入真实的 Bambu 对象 ID，而不是根据显示顺序猜测。

{
  "three_mf_path": "/Users/yourname/Downloads/bracket.gcode.3mf",
  "plate_index": 0
}

print_collar_charm

用于已准备好的两件式狗项圈吊饰工作流的高级封装工具。此工具有意针对特定场景设计：它要求使用已准备好的两件式吊饰项目，并应用固定的料槽策略。

• 较小的内侧对象 -> 黑色 -> AMS 1 料槽 1
• 较大的外侧对象 -> 白色 -> AMS 2 料槽 1

此工具将：

1. 解析本地 .3mf 或 template_name。
2. 如果 3MF 仍是未切片项目，则自动切片。
3. 检查 Metadata/plate_1.json，确定较小的内侧部件和较大的外侧部件。
4. 在打印机上预检所需的 AMS 料槽。
5. 使用 ams_slots，通过现有的 H2 安全 print3mf 路径发送打印任务。

{
  "template_name": "collars/letter_charm_a",
  "bambu_model": "h2d",
  "host": "192.168.1.100",
  "bambu_serial": "03W09C123456789",
  "bambu_token": "your_access_token",
  "bed_leveling": true,
  "flow_calibration": true,
  "vibration_calibration": true,
  "timelapse": false
}

你也可以直接传入 source_path，而不是 template_name。

此封装工具目前假定：

• 输入是已准备好的两件式吊饰 .3mf，而不是需要生成颜色区域的裸 STL 文件
• 所选构建板恰好有 2 个对象
• 所选构建板恰好使用 2 个耗材位置
• 较小的对象是内嵌件／字母，较大的对象是外壳

如果项目不符合这些假设，工具会快速失败并返回结构化错误，而不会自行猜测。角色到颜色以及颜色到料槽的映射在代码中彼此隔离，因此后续版本可以逐步支持客户指定颜色，而无需整体替换此封装工具。

切片工具

**注意：**经过验证的工作流是在 Bambu Studio（GUI）中切片，然后将生成的 .gcode.3mf 传给 print_3mf。以下由 CLI 驱动的切片工具（slice_stl、slice_with_template）可以使用，但容易受到配置文件漂移的影响，因此不建议用于生产打印。请参阅切片指南。

list_templates

列出本地注册表目录中的已保存模板。你可以使用 BAMBU_TEMPLATE_DIR 覆盖注册表根目录。

{}

每条结果都包含模板 name、绝对 path、源类型，以及注册表中的相对路径。随后你可以传入 template_name，用于 get_slice_settings、slice_stl 或 print_3mf，而无需传入原始路径。

将本地 3mf、json 或 .config 文件复制到模板注册表，并使用可复用的模板名称注册。

{
  "source_path": "/path/to/sliced_project.3mf",
  "template_name": "collars/p1p_petg_default"
}

此操作会在模板注册表目录下创建目标文件，并立即使其可供 list_templates、get_slice_settings、slice_with_template、slice_stl 和 print_3mf 使用。

get_slice_settings

检查已保存的 3MF 模板或已提取的 JSON/config 配置文件中嵌入的切片器设置，无需进行切片。

{
  "template_name": "h2s_template"
}

此操作会返回关键信息设置的简要摘要，例如打印机预设、默认打印配置文件、耗材配置文件、层高、填充密度、外壳数量、支撑模式和热床类型。它接受 source_path 或 template_name。对于 3MF 输入，它还会将提取出的设置数据写入临时路径，以便直接复用结果。

slice_with_template

使用本地注册表中的命名模板对 STL 或 3MF 进行切片。这是面向模板工作流的 slice_stl 高级封装。

{
  "stl_path": "/path/to/model.stl",
  "template_name": "collars/p1p_petg_default",
  "bambu_model": "p1p"
}

此操作使用命名模板作为切片配置文件来源，并仍支持实时选择打印机耗材，除非你明确覆盖 load_filaments。模板设置会在切片时应用，之后的 print_3mf 步骤会根据新切片的输出计算 H2 安全的 AMS 映射。

slice_stl

使用外部切片器对 STL 或 3MF 文件进行切片，并返回输出文件的路径。输出文件为切片后的 3MF（适用于 BambuStudio、OrcaSlicer 和 FULU OrcaSlicer-bambulab）或 G-code 文件（适用于 PrusaSlicer、Cura、Slic3r）。

{
  "stl_path": "/path/to/model.stl",
  "slicer_type": "bambustudio",
  "bambu_model": "p1s"
}

slicer_type 可选值：bambustudio、orcaslicer、orcaslicer-bambulab（FULU）、prusaslicer、cura、slic3r。别名包括 fulu-orca 和 orca-studio。如果省略，则使用 SLICER_TYPE 环境变量的值（默认值：bambustudio）。

FULU/Orca CLI 安全性： 从 1.1.11 版起，这些后端要求使用所选安装版本中的准确模型/喷嘴预设，并会在配置文件准备失败时停止。进程级覆盖无法绕过此限制。请参阅配置和验证限制。

OrcaSlicer CLI 变换： 当 scale 或 rotate_x/rotate_y 使对象在排列时移到热床下方，OrcaSlicer 2.4.2 的 CLI 会发生段错误；对于 STL 输入，这是默认行为。OrcaSlicer 在 2.4.2 之后修复了此问题，详见 #14415，首次发布于 2.5.0-alpha。对于使用 orcaslicer 或 orcaslicer-bambulab 的 STL 输入，服务会按照 CLI 的顺序，对网格副本应用 scale 和旋转，并省略这些标志。对于 3MF 输入，如果 scale 大于 1，或 rotate_x、rotate_y 与 arrange: true 同时使用，则会拒绝处理。repetitions 会使用 Orca 的 --clone-objects 复制 STL。clone_objects 接受一个总数，因为 CLI 会按加载的文件计算副本数。使用 arrange: false 时，未置于热床上的 STL 无法切片。错误信息会说明切片器自身报告的原因。

如果未指定，slicer_path 和 slicer_profile 会分别使用 SLICER_PATH 和 SLICER_PROFILE 环境变量。按调用设置的 slicer_path 覆盖值要求设置 MCP_ALLOW_EXECUTABLE_ARG=1。

如果要使用已保存的模板进行切片，可以提供 template_3mf_path 或 template_name。template_name 会通过为服务配置的本地模板注册表目录解析。

要在 Bambu 打印机上打印，推荐的工作流是：从所选的 Bambu 兼容切片器导出切片后的 3MF，然后将该输出路径传递给 print_3mf。

BambuStudio 切片器选项

当 slicer_type 为 bambustudio（默认值）时，slice_stl 还支持以下参数：

示例：自动调整方向并切片，生成 3 个副本

{
  "stl_path": "/path/to/model.stl",
  "bambu_model": "p1s",
  "orient": true,
  "arrange": true,
  "repetitions": 3
}

智能默认值（print_3mf 自动切片）

当 print_3mf 检测到未切片的 3MF 并自动对其切片时，会自动应用以下默认值：

• uptodate: true -- 避免下载的 3MF 出现过时配置错误
• ensure_on_bed: true -- 安全措施：将悬空模型抬至构建板上
• min_save: true -- 输出更小的文件，加快通过 FTP 上传到打印机的速度
• skip_modified_gcodes: true -- 移除其他用户配置文件中的自定义 gcodes

这些默认值可减少配置文件过时导致的问题；打印前请检查下载的模型及其切片预览。直接调用 slice_stl 时，你可以完全控制每个标志。

高级工具

Blender MCP

使用标准的 stdio Blender MCP 服务，并设置 BLENDER_MCP_COMMAND 和 BLENDER_MCP_ARGS。对于常见的 Blender MCP 服务，请安装 uv 及与其匹配的 Blender 插件，启用该插件，并在 Blender 中启动连接。将命令设为完整的 uvx 路径，并将参数数组设为 ["blender-mcp"]。Claude Desktop 扩展也提供这两项可选设置。 无需配置 Blender 即可使用打印机工具。

1. 使用 {"connect": true} 调用 blender_mcp_status，以初始化服务 并发现其工具和输入架构。MCP 服务已连接并不能单独证明 Blender 插件正在运行。
2. 使用发现的工具名称及其参数调用 blender_mcp_call。将返回完整的 MCP 结果，包括图像和错误。例如：

{
  "tool_name": "get_scene_info",
  "arguments": {"user_prompt": "Inspect the scene before preparing a print."}
}

对于高级 Blender 操作，请转发 execute_blender_code，并提供 code 和用户原始的 user_prompt。这些调用可能会编辑当前场景。 请使用发现的架构，不要假设某个工具一定存在。

标准 MCP 编辑辅助工具会导入 STL，按顺序应用编辑，并导出 STL，而不会替换输入文件或现有输出文件。支持的操作包括 decimate:<ratio>（大于 0 且不超过 1）、remesh:<voxel size>（以 STL 坐标单位表示的正数）和 boolean_union:<STL path>。其他操作可使用 blender_mcp_call。两个进程都必须能够访问相同的文件路径。 当 BLENDER_MCP_COMMAND 选择标准 MCP 时，所公布的工具架构要求预览和执行都必须显式提供 output_path。仅使用旧版桥接的配置为保持兼容，仍可省略 output_path。

{
  "stl_path": "/path/to/model.stl",
  "output_path": "/path/to/model-edited.stl",
  "operations": ["decimate:0.5"],
  "user_prompt": "Reduce the triangle count of this model for printing.",
  "execute": false
}

默认预览会返回计划和生成的 Python 代码，不会启动 Blender。将 execute 设为 true 即可运行。标准编辑成功后会返回 output_verified: true、output_path、字节数和三角形数量；这些信息是在检查匹配的导出回执和有效的有限网格后返回的。该辅助工具会保留现有场景对象，并要求处于对象模式。切片前请检查结果；STL 有效并不代表它适合打印。

桥接会强制执行请求期限、关闭子进程连接，并且绝不会重放中断的编辑请求。超时后，请先检查 Blender，再尝试重新编辑，因为执行可能已经开始。

现有自定义可执行文件仍可通过 BLENDER_MCP_BRIDGE_COMMAND 使用。它们会收到包含请求文件和操作的 MCP_BLENDER_PAYLOAD；其结果会明确报告 output_verified: false。请求执行时，如果缺少可执行文件配置，就会报错。除非设置 MCP_ALLOW_EXECUTABLE_ARG=1，否则会禁用每次调用时对旧版 bridge_command 的覆盖。