bambu-printer-mcp 1.1.9 → 1.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/CONTRIBUTORS.md +10 -4
  2. package/README.md +185 -369
  3. package/dist/index.js +1 -1
  4. package/dist/slicer/profile-flatten.d.ts +5 -1
  5. package/dist/slicer/profile-flatten.js +31 -12
  6. package/dist/stl/stl-manipulator.js +36 -15
  7. package/package.json +1 -1
  8. package/src/index.ts +1 -1
  9. package/src/slicer/profile-flatten.ts +37 -12
  10. package/src/stl/stl-manipulator.ts +42 -18
package/README.md CHANGED
@@ -1,9 +1,13 @@
1
1
  # bambu-printer-mcp
2
2
 
3
+ > **Thank you, [FULU Foundation](https://www.fulu.org/), [Louis Rossmann](https://www.youtube.com/watch?v=1jhRqgHxEP8), and the [OrcaSlicer-bambulab contributors](https://github.com/FULU-Foundation/OrcaSlicer-bambulab).** We stand with open-source developers, the right to repair, and your right to control hardware you own. You should be able to choose your software and print without a vendor cloud standing in the way.
4
+ >
5
+ > **Want to skip Bambu's software and cloud?** Use FULU OrcaSlicer-bambulab to slice and export, then this MCP's direct LAN path on supported printers and firmware. That workflow does not require Bambu Studio, Bambu Connect, or Bambu Cloud. Start with the [FULU setup guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md). The optional BambuNetwork bridge is a separate path that still uses Bambu's networking runtime; cloud jobs still use Bambu's services.
6
+
3
7
  [![npm version](https://img.shields.io/npm/v/bambu-printer-mcp.svg)](https://www.npmjs.com/package/bambu-printer-mcp)
4
8
  [![License: GPL-2.0](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
5
9
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
6
- [![Node.js Version](https://img.shields.io/badge/node-%3E%3D%2018.0.0-green.svg)](https://nodejs.org/en/download/)
10
+ [![Tested with Node.js 24](https://img.shields.io/badge/tested%20with-Node.js%2024-green.svg)](https://nodejs.org/en/download/)
7
11
  [![GitHub stars](https://img.shields.io/github/stars/DMontgomery40/bambu-printer-mcp.svg?style=social&label=Star)](https://github.com/DMontgomery40/bambu-printer-mcp)
8
12
  [![Downloads](https://img.shields.io/npm/dm/bambu-printer-mcp.svg)](https://www.npmjs.com/package/bambu-printer-mcp)
9
13
 
@@ -15,58 +19,83 @@ This is a stripped-down, Bambu-only fork of [mcp-3D-printer-server](https://gith
15
19
 
16
20
  ---
17
21
 
18
- ## What's new in bambu-printer-mcp
22
+ ## Set up with your agent
23
+
24
+ Tell your agent your printer's **model and LAN address**, if you know them, then copy and paste this:
19
25
 
20
- This fork adds a substantial set of printer control tools beyond the upstream `mcp-3D-printer-server`. Everything listed below is unique to this package.
26
+ ```text
27
+ Install bambu-printer-mcp in the agent/harness I'm using now.
21
28
 
22
- ### v1.1.8 — reliable installs, printer fixes, and Blender MCP
29
+ Read https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md
30
+ and https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md
31
+ for the current setup instructions and supported workflows.
23
32
 
24
- - Fix delayed H2 status crashes and preserve machine-specific G-code when resolving Bambu profiles.
25
- - Correct P2S and full-size A1 print routing while preserving other models' existing behavior.
26
- - Install a Claude Desktop extension with prompted settings; keep local credentials and models out of packaged artifacts.
27
- - Connect to standard Blender MCP servers, discover and call their tools, and verify STL edit/export results.
28
- - Preserve filament-slot order and isolate temporary files between concurrent jobs and server instances.
33
+ Detect my OS and harness, then use its native MCP configuration or installer.
34
+ Preserve my existing servers and settings. Prefer the published npm package
35
+ (npx -y bambu-printer-mcp, stdio); use Node.js 24 if a runtime is needed.
29
36
 
30
- ### v1.1.0 — AMS auto-match, camera snapshot, pause/resume, skip objects
37
+ Find existing printer settings in relevant local configuration or available
38
+ LAN discovery. Confirm the detected printer's model, address, and identity
39
+ with me before connecting. Ask only for values you cannot find:
40
+ PRINTER_HOST, BAMBU_MODEL, BAMBU_SERIAL, and BAMBU_TOKEN (the LAN access code).
41
+ Keep credentials in local/private configuration; do not repeat access codes
42
+ or tokens in chat. Never guess the printer model.
31
43
 
32
- - **AMS auto-match by RFID** (`auto_match_ams` on `print_3mf`) — resolves sliced 3MF filament requirements against live AMS inventory. Handles same-SKU different-color filaments. Dry-run with `resolve_3mf_ams_slots`.
33
- - **Structured AMS inventory** (`get_printer_filaments`) — per-tray display names, profile resolution tier (`exact-model-nozzle`/`model`/`generic`/`unresolved`), match confidence, and a summary with recommended auto-slice filament.
34
- - **AMS settle-time retry** — transparently retries when AMS data hasn't arrived on the first MQTT push from an idle printer.
35
- - **Camera snapshot** (`camera_snapshot`) — JPEG from the chamber camera. TCP-on-6000 for A1/P1S/P1P, RTSP via ffmpeg for X1/P2S/H2 series.
36
- - **Pause / resume** (`pause_print`, `resume_print`) — alongside the existing `cancel_print`.
37
- - **Skip objects** (`skip_objects`) — skip specific object IDs during a running multi-object print. IDs from `list_3mf_plate_objects`.
38
- - **HMS diagnostics** (`printer://{host}/hms` MCP resource) — read-only error summary with automatic settle retry.
39
- - **Utility controls** — `set_print_speed` (silent/standard/sport/ludicrous), `clear_hms_errors`, `reread_ams_rfid`, `set_airduct_mode` (cooling/heating for H2/P2).
40
- - **H2-family-safe print path** — correct `project_file` format with `ams_mapping2` parallel array, H2 firmware quirks handled.
41
- - **BambuStudio CLI auto-flatten** (automatic for BBL profiles) — works around upstream profile inheritance bugs.
42
- - **Print collar charm** (`print_collar_charm`) — specialized two-color wrapper with fixed tray policy.
44
+ Use direct LAN printing by default. Explain any LAN/Developer Mode setting
45
+ I need to enable. Prefer FULU OrcaSlicer-bambulab GUI slicing/export; discover
46
+ an existing slicer before suggesting an install. For FULU/Orca CLI auto-slicing,
47
+ require MCP 1.1.11+ and its matching installed profile tree (see guide).
48
+ A slicer is not needed here to print a pre-sliced file. Configure the optional FULU
49
+ BambuNetwork bridge only if I choose it, and explain its runtime/auth needs.
50
+ X2D supports status and slicing here, but direct printing is not supported.
43
51
 
44
- ### v1.1.1 — AMS dryer control
52
+ If this harness does not already provide code mode or an equivalent, suggest
53
+ a compatible code-mode integration as an optional addition. It is not required;
54
+ finish ordinary MCP setup without it unless I choose to add it.
45
55
 
46
- - **AMS dryer start/stop** (`set_ams_drying`) — sends `print.ams_control` MQTT command. Works on heated AMS units (AMS Pro / AMS-HT). Action: `start` or `stop`, target by AMS index 0–3.
47
- - Same-SKU different-color fix for `auto_match_ams`.
48
- - AMS and HMS settle-time retry for idle printers.
49
- - Validation script (`scripts/validate-printer.mjs`) for live printer testing.
56
+ Verify that the MCP initializes, lists its tools, and reads printer status.
57
+ Do not start a print or change printer settings as a setup test. Tell me what
58
+ worked and whether I need to restart or reload the harness.
59
+ ```
50
60
 
51
- > Full changelog at [CHANGELOG.md](./CHANGELOG.md).
61
+ [Setup reference](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md) · [FULU guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md) · [Optional code mode](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md#optional-code-mode)
52
62
 
53
63
  <details>
54
- <summary><strong>Click to expand Table of Contents</strong></summary>
64
+ <summary><strong>Start here</strong></summary>
65
+
66
+ ## Start here
67
+
68
+ | I want to… | Read next |
69
+ |---|---|
70
+ | Use open-source slicing and a cloud-free print workflow | [FULU setup: slicer, LAN, and optional bridge](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md) |
71
+ | Connect this MCP to my agent | [Copy the setup request](#set-up-with-your-agent) |
72
+ | Troubleshoot setup or configure it manually | [Installation, environment variables, and LAN reference](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SETUP.md) |
73
+ | Prepare a printable file or troubleshoot slicing | [Slicing guide and model routing](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md) |
74
+ | Choose filament trays or inspect a printer | [AMS setup](#ams-automatic-material-system-setup) and [printer tools](#printer-control-tools) |
75
+ | Edit an STL through Blender | [Blender MCP setup](#blender-mcp) |
76
+ | See release changes or contributor credit | [Changelog](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/CHANGELOG.md), [releases](https://github.com/DMontgomery40/bambu-printer-mcp/releases), and [contributors](./CONTRIBUTORS.md) |
77
+
78
+ </details>
79
+
80
+ <details>
81
+ <summary><strong>What's new in bambu-printer-mcp</strong></summary>
82
+
83
+ ## What's new in bambu-printer-mcp
84
+
85
+ See the [changelog](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/CHANGELOG.md) for versioned changes. Recent releases add reliable npm and desktop-extension installs, standard Blender MCP integration, corrected P2S/A1 routing, and safer multi-filament CLI slicing. X2D status and slicing are available; **direct X2D printing remains unsupported** pending its native eMMC transport.
86
+
87
+ </details>
88
+
89
+ <details>
90
+ <summary><strong>Table of Contents</strong></summary>
55
91
 
56
92
  ## Table of Contents
57
93
 
94
+ - [Start here](#start-here)
58
95
  - [Description](#description)
96
+ - [FULU and open-source printing](#fulu-and-open-source-printing)
59
97
  - [Features](#features)
60
- - [Installation](#installation)
61
- - [Prerequisites](#prerequisites)
62
- - [Run without installing (npx)](#run-without-installing-npx)
63
- - [Install globally from npm](#install-globally-from-npm)
64
- - [Install from source](#install-from-source)
65
- - [Configuration](#configuration)
66
- - [Environment variables reference](#environment-variables-reference)
67
- - [Usage](#usage)
68
- - [Enabling Developer Mode (Required)](#enabling-developer-mode-required)
69
- - [Finding Your Bambu Printer's Serial Number and Access Token](#finding-your-bambu-printers-serial-number-and-access-token)
98
+ - [Set up with your agent](#set-up-with-your-agent)
70
99
  - [AMS (Automatic Material System) Setup](#ams-automatic-material-system-setup)
71
100
  - [Bambu Communication Notes (MQTT and FTP)](#bambu-communication-notes-mqtt-and-ftp)
72
101
  - [What this fork fixes](#what-this-fork-fixes)
@@ -83,23 +112,41 @@ This fork adds a substantial set of printer control tools beyond the upstream `m
83
112
  - [Memory usage](#memory-usage)
84
113
  - [STL manipulation limitations](#stl-manipulation-limitations)
85
114
  - [Performance considerations](#performance-considerations)
115
+ - [Acknowledgements](#acknowledgements)
86
116
  - [License](#license)
87
117
 
88
118
  </details>
89
119
 
90
- ---
120
+ <details>
121
+ <summary><strong>Description</strong></summary>
91
122
 
92
123
  ## Description
93
124
 
94
- `bambu-printer-mcp` is a Model Context Protocol server that gives Claude (or any MCP client) direct control over Bambu Lab 3D printers. The verified end-to-end path is: **slice in Bambu Studio, export a `.gcode.3mf`, hand the path to `print_3mf`** — the server reads the slicer's metadata out of the 3MF, builds the correct AMS mapping, uploads over FTPS, and starts the print via an MQTT `project_file` command. See [docs/SLICING.md](./docs/SLICING.md) for the full recipe and why in-process slicing is not the recommended path.
125
+ `bambu-printer-mcp` is a Model Context Protocol server for Bambu Lab 3D printers. A straightforward workflow is: **slice in FULU OrcaSlicer-bambulab, OrcaSlicer, or Bambu Studio, export a sliced `.gcode.3mf`, then pass its path to `print_3mf`**. The default direct LAN path uploads via FTPS and chooses the MQTT command for the target model. See the [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md) for CLI options, model routing, and validation limits.
95
126
 
96
127
  **What this is not.** This package intentionally supports only Bambu Lab printers. It does not include adapters for OctoPrint, Klipper (Moonraker), Duet, Repetier, Prusa Connect, or Creality Cloud. If you need multi-printer support, use the parent project [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) instead.
97
128
 
98
- **Why a separate package?** The parent project carries all printer adapters in a single binary. When working exclusively with Bambu hardware, that breadth adds unnecessary weight. This fork strips the project to its Bambu core for a smaller, faster install. Both packages share the same protocol fixes and safety features.
129
+ **Why a separate package?** The parent project carries all printer adapters in a single binary. When working exclusively with Bambu hardware, that breadth adds unnecessary weight. This fork strips the project to its Bambu core for a smaller, faster install. See each project's changelog for its current fixes and supported workflows.
99
130
 
100
131
  **Note on resource usage.** STL manipulation loads entire mesh geometry into memory. For large or complex STL files (greater than 10 MB), these operations can be memory-intensive. See [General Limitations and Considerations](#general-limitations-and-considerations) for details.
101
132
 
102
- ---
133
+ </details>
134
+
135
+ <details>
136
+ <summary><strong>FULU and open-source printing</strong></summary>
137
+
138
+ ## FULU and open-source printing
139
+
140
+ [FULU OrcaSlicer-bambulab](https://github.com/FULU-Foundation/OrcaSlicer-bambulab) is a supported slicer target (`SLICER_TYPE=orcaslicer-bambulab`; aliases include `fulu-orca` and `orca-studio`). Use its GUI to export a sliced project for direct LAN printing, or configure its CLI with matching installed profiles. From 1.1.11, FULU/Orca share the [machine-preset gate and profile safety checks](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#fulu-and-orca-cli-safety-limit).
141
+
142
+ The optional FULU **BambuNetwork bridge** exposes `bambu_network_bridge_status`, `bambu_network_call`, and `print_3mf_bambu_network`, also reachable through `print_3mf` with `connection_mode: "bambu_network"`. Slicer selection does not enable the bridge. It needs a separately installed FULU runtime and an explicit launch command; cloud printing also needs an authenticated BambuNetwork session.
143
+
144
+ **[Follow the FULU setup guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md)** for the direct LAN recipe, Linux/Windows/macOS bridge setup, connection probes, authentication, and troubleshooting. Bridge protocol tests and a successful handshake do not establish a successful physical print.
145
+
146
+ </details>
147
+
148
+ <details>
149
+ <summary><strong>Features</strong></summary>
103
150
 
104
151
  ## Features
105
152
 
@@ -107,8 +154,8 @@ This fork adds a substantial set of printer control tools beyond the upstream `m
107
154
  - Query live AMS inventory with resolved Bambu/Orca filament profile paths via `get_printer_filaments`. Includes per-tray display names, match confidence (`high`/`medium`/`low`/`none`), resolution tier (`exact-model-nozzle`/`model`/`generic`/`unresolved`), and a summary with recommended auto-slice filament. Retries automatically when AMS data hasn't arrived yet (common on first MQTT push from idle printers).
108
155
  - List, upload, and delete files on the printer's SD card via FTPS
109
156
  - Capture a JPEG snapshot from the chamber camera. Supports A1, A1 mini, P1S, P1P (TCP-on-6000), and X1, X1C, X1E, P2S, H2, H2S, H2D, H2C, H2D Pro, X2D (RTSP via ffmpeg). Requires ffmpeg in PATH for the RTSP path.
110
- - Upload and print pre-sliced `.gcode.3mf` files with full plate selection and calibration flag control (recommended path — see [docs/SLICING.md](./docs/SLICING.md))
111
- - Slice through BambuStudio CLI with automatic BBL inheritance/include resolution, per-slot filament colours, and fallback prime-tower placement for multi-nozzle printers. Missing dependencies stop the slice; custom settings and saved project tower positions are preserved. Multi-colour slicing is verified by the contributor on BambuStudio 02.08.02.60 for Windows; older CLI versions have separate limitations. See [docs/SLICING.md](./docs/SLICING.md).
157
+ - Upload and print pre-sliced `.gcode.3mf` files with full plate selection and calibration flag control (recommended path — see [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md))
158
+ - Slice through BambuStudio CLI with automatic BBL inheritance/include resolution, per-slot filament colours, and fallback prime-tower placement for multi-nozzle printers. Missing dependencies stop the slice; custom settings and saved project tower positions are preserved. Multi-colour slicing is verified by the contributor on BambuStudio 02.08.02.60 for Windows; older CLI versions have separate limitations. See [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
112
159
  - Recognize X2D status and slice with its own installed BambuStudio preset (`BAMBU_MODEL=x2d`). **Direct X2D printing is not supported yet**: the internal eMMC transport is pending. These print requests stop before slicing, uploading, or issuing printer commands. Print exported projects through a supported slicer instead.
113
160
  - Parse AMS mapping from the 3MF's embedded slicer metadata (`Metadata/plate_<n>.json` + gcode filament header) and send it correctly formatted per the OpenBambuAPI spec, with correct H2S/H2D/H2C `ams_mapping2` parallel array format
114
161
  - **Auto-match AMS slots by RFID** (`auto_match_ams` flag on `print_3mf`). Resolves required `tray_info_idx` from the sliced 3MF against live AMS inventory. Handles same-SKU different-color filaments by matching on `(tray_info_idx, tray_color)` and tracking already-claimed slots. Dry-run with `resolve_3mf_ams_slots` before printing.
@@ -122,7 +169,7 @@ This fork adds a substantial set of printer control tools beyond the upstream `m
122
169
  - Start G-code files already stored on the printer
123
170
  - **Collar charm print wrapper** (`print_collar_charm`) — specialized two-color workflow with fixed tray policy for inner (black, AMS 1 slot 1) and outer (white, AMS 2 slot 1) charm parts
124
171
  - STL manipulation: scale, rotate, extend base, merge vertices, center at origin, lay flat, and inspect model info
125
- - Slice STL or 3MF files using BambuStudio, OrcaSlicer, PrusaSlicer, Cura, or Slic3r
172
+ - Slice STL or 3MF files using an external CLI. BambuStudio, FULU, and Orca require the exact machine preset and resolve BBL dependencies before slicing; see [FULU/Orca CLI setup and validation limits](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#fulu-and-orca-cli-safety-limit).
126
173
  - Inspect slicer settings from a saved 3MF template or extracted profile via `get_slice_settings`
127
174
  - Enumerate saved slicing templates from the local registry via `list_templates`
128
175
  - Save templates into the local registry via `save_template`
@@ -132,292 +179,10 @@ This fork adds a substantial set of printer control tools beyond the upstream `m
132
179
  - Optional Blender MCP bridge for advanced mesh operations
133
180
  - Dual transport: stdio (default, for Claude Desktop / Claude Code) and Streamable HTTP
134
181
 
135
- ---
136
-
137
- ## Installation
138
-
139
- ### Prerequisites
140
-
141
- - Node.js 18 or higher
142
- - npm
143
- - **BambuStudio** *(optional -- only needed for slicing)* -- [download from bambulab.com](https://bambulab.com/en/download/studio). Required by `slice_stl` and `print_3mf` auto-slice (when a 3MF has no embedded gcode). Not needed if you only print pre-sliced 3MF files. Default path: `/Applications/BambuStudio.app/Contents/MacOS/BambuStudio` (macOS); set `SLICER_PATH` if installed elsewhere.
144
-
145
- ### Run without installing (npx)
146
-
147
- The fastest way to get started. No global install required:
148
-
149
- ```bash
150
- npx bambu-printer-mcp
151
- ```
152
-
153
- Set environment variables inline or via a `.env` file in your working directory (see [Configuration](#configuration)).
154
-
155
- ### Install globally from npm
156
-
157
- ```bash
158
- npm install -g bambu-printer-mcp
159
- ```
160
-
161
- After installation, the `bambu-printer-mcp` command is available in your PATH.
162
-
163
- ### Install from source
164
-
165
- ```bash
166
- git clone https://github.com/DMontgomery40/bambu-printer-mcp.git
167
- cd bambu-printer-mcp
168
- npm install
169
- npm run build
170
- npm link
171
- ```
172
-
173
- `npm link` makes the `bambu-printer-mcp` binary available globally without publishing to npm.
174
-
175
- ---
176
-
177
- ## Configuration
178
-
179
- Create a `.env` file in the directory where you run the server, or pass environment variables directly in your MCP client config. All printer connection variables can also be passed as tool arguments on a per-call basis, which is useful when working with multiple printers.
180
-
181
- ```env
182
- # --- Bambu printer connection (required for all printer tools) ---
183
- PRINTER_HOST=192.168.1.100 # IP address of your Bambu printer on the local network
184
- BAMBU_SERIAL=01P00A123456789 # Printer serial number (see Finding Your Serial Number below)
185
- BAMBU_TOKEN=your_access_token # LAN access token from printer touchscreen
186
- # Compatible aliases also accepted:
187
- # BAMBU_PRINTER_HOST / BAMBU_PRINTER_SERIAL / BAMBU_PRINTER_ACCESS_TOKEN
188
-
189
- # --- Printer model (CRITICAL for safe operation) ---
190
- BAMBU_MODEL=p1s # Your printer model: p1s, p1p, p2s, x1c, x1e, a1, a1mini, h2d, h2s, h2c, x2d
191
- # Alias also accepted: BAMBU_PRINTER_MODEL
192
- BED_TYPE=textured_plate # Bed plate type: textured_plate, cool_plate, engineering_plate, hot_plate, supertack_plate
193
- NOZZLE_DIAMETER=0.4 # Nozzle diameter in mm (default: 0.4)
194
-
195
- # --- Slicer configuration (required for slice_stl and print_3mf auto-slice) ---
196
- SLICER_TYPE=bambustudio # Options: bambustudio, prusaslicer, orcaslicer, cura, slic3r
197
- SLICER_PATH=/Applications/BambuStudio.app/Contents/MacOS/BambuStudio
198
- # Default on macOS. Adjust for your OS and install path.
199
- # Alias also accepted: BAMBU_STUDIO_PATH
200
- SLICER_PROFILE= # Optional: path to a slicer profile/config file
201
-
202
- # --- Temporary file directory ---
203
- TEMP_DIR=/tmp/bambu-mcp-temp # Directory for intermediate files. Created automatically if absent.
204
-
205
- # --- MCP transport ---
206
- MCP_TRANSPORT=stdio # Options: stdio (default), streamable-http
207
-
208
- # --- Streamable HTTP transport (only used when MCP_TRANSPORT=streamable-http) ---
209
- MCP_HTTP_HOST=127.0.0.1
210
- MCP_HTTP_PORT=3000
211
- MCP_HTTP_PATH=/mcp
212
- MCP_HTTP_STATEFUL=true
213
- MCP_HTTP_JSON_RESPONSE=true
214
- MCP_HTTP_ALLOWED_ORIGINS=http://localhost
215
-
216
- # --- Optional standard Blender MCP server ---
217
- BLENDER_MCP_COMMAND=uvx # Executable or full path; no shell command string
218
- BLENDER_MCP_ARGS='["blender-mcp"]'
219
- BLENDER_MCP_TIMEOUT_MS=120000
220
- # Start the matching MCP addon inside Blender.
221
- # Legacy custom executable bridge (optional): BLENDER_MCP_BRIDGE_COMMAND=
222
- ```
223
-
224
- ### Environment variables reference
225
-
226
- | Variable | Default | Required | Description |
227
- |---|---|---|---|
228
- | `PRINTER_HOST` | `localhost` | Yes | IP address of the Bambu printer. Alias: `BAMBU_PRINTER_HOST` |
229
- | `BAMBU_SERIAL` | | Yes | Printer serial number. Alias: `BAMBU_PRINTER_SERIAL` |
230
- | `BAMBU_TOKEN` | | Yes | LAN access token. Alias: `BAMBU_PRINTER_ACCESS_TOKEN` |
231
- | `BAMBU_MODEL` | | **Yes** | Printer model: `p1s`, `p1p`, `p2s`, `x1c`, `x1e`, `a1`, `a1mini`, `h2d`, `h2s`, `h2c`, `x2d`. **Required for safe operation** -- determines the correct G-code generation. Alias: `BAMBU_PRINTER_MODEL`. If omitted and the MCP client supports elicitation, the server will ask you interactively. Use `h2c` for H2C and `x2d` for X2D; do not use `h2d` as a fallback. |
232
- | `BED_TYPE` | `textured_plate` | No | Bed plate type: `textured_plate`, `cool_plate`, `engineering_plate`, `hot_plate`, `supertack_plate` |
233
- | `NOZZLE_DIAMETER` | `0.4` | No | Nozzle diameter in mm. Used to select the correct BambuStudio machine preset. |
234
- | `SLICER_TYPE` | `bambustudio` | No | Slicer to use for slicing operations |
235
- | `SLICER_PATH` | BambuStudio macOS path | No | Full path to the slicer executable. Alias: `BAMBU_STUDIO_PATH` |
236
- | `SLICER_PROFILE` | | No | Path to a slicer profile or config file |
237
- | `TEMP_DIR` | private folder under the system temporary directory | No | Intermediate files; each server instance gets its own folder unless explicitly configured |
238
- | `MCP_TRANSPORT` | `stdio` | No | Transport mode: `stdio` or `streamable-http` |
239
- | `MCP_HTTP_HOST` | `127.0.0.1` | No | HTTP bind address (HTTP transport only) |
240
- | `MCP_HTTP_PORT` | `3000` | No | HTTP port (HTTP transport only) |
241
- | `MCP_HTTP_PATH` | `/mcp` | No | HTTP endpoint path (HTTP transport only) |
242
- | `MCP_HTTP_STATEFUL` | `true` | No | Enable stateful HTTP sessions |
243
- | `MCP_HTTP_JSON_RESPONSE` | `true` | No | Return structured JSON alongside text responses |
244
- | `MCP_HTTP_ALLOWED_ORIGINS` | | No | Comma-separated list of allowed CORS origins |
245
- | `BLENDER_MCP_COMMAND` | | No | Trusted executable for a standard stdio Blender MCP server, e.g. full path to `uvx` |
246
- | `BLENDER_MCP_ARGS` | `[]` | No | JSON array of server arguments, e.g. `["blender-mcp"]`; no shell parsing |
247
- | `BLENDER_MCP_TIMEOUT_MS` | `120000` | No | Connection/discovery/call deadline, 100–300000 ms; interrupted edits are never retried automatically |
248
- | `BLENDER_MCP_BRIDGE_COMMAND` | | No | Legacy custom executable receiving `MCP_BLENDER_PAYLOAD`; separate from the standard MCP integration |
249
- | `BAMBU_CLI_FLATTEN` | automatic | No | Legacy setting; BBL profile resolution now always runs when profiles contain inheritance or includes. A false/unset value cannot bypass required machine G-code. Standalone custom files without dependencies pass through. See [docs/SLICING.md](./docs/SLICING.md). |
250
- | `BAMBU_PROFILES_ROOT` | derived from `SLICER_PATH` | No | Override path to the BambuStudio `Resources/profiles` directory used by the CLI flattener. Useful for non-standard installs or dev environments. |
251
-
252
- SuperTack can be passed for pre-sliced print jobs, but BambuStudio CLI slicing currently fails fast for `supertack_plate` because the accepted CLI bed identifier is not verified. Use a pre-sliced 3MF for SuperTack until this is confirmed.
253
-
254
- ---
255
-
256
- ## Usage
257
-
258
- Add this server to your MCP client's config (Claude Desktop, Claude Code, Cursor, Codex CLI, or any MCP-compatible client). The config format is the same everywhere -- an `mcpServers` entry with the command and env vars:
259
-
260
- ```json
261
- {
262
- "mcpServers": {
263
- "bambu-printer": {
264
- "command": "npx",
265
- "args": ["-y", "bambu-printer-mcp"],
266
- "env": {
267
- "PRINTER_HOST": "192.168.1.100",
268
- "BAMBU_SERIAL": "01P00A123456789",
269
- "BAMBU_TOKEN": "your_access_token",
270
- "BAMBU_MODEL": "p1s",
271
- "SLICER_TYPE": "bambustudio",
272
- "SLICER_PATH": "/Applications/BambuStudio.app/Contents/MacOS/BambuStudio"
273
- }
274
- }
275
- }
276
- }
277
- ```
278
-
279
- Where this config lives depends on your client:
280
-
281
- | Client | Config location |
282
- |--------|----------------|
283
- | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
284
- | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
285
- | Claude Code (project) | `.mcp.json` in project root |
286
- | Claude Code (global) | `~/.claude/settings.json` |
287
- | Cursor | MCP settings in Cursor preferences |
288
- | Codex CLI | MCP config per Codex docs |
289
-
290
- Restart your client after editing the config.
291
-
292
- ### Alternative: Claude Desktop extension (.mcpb)
293
-
294
- You can install this server into Claude Desktop without editing JSON by using the `.mcpb` extension bundle. Download `bambu-printer-mcp.mcpb` from the [latest release](https://github.com/DMontgomery40/bambu-printer-mcp/releases), double-click it, and Claude Desktop's extension wizard will register the server. You'll be prompted for your printer IP, serial number, LAN access code, and printer model -- the same values as the `mcpServers` config above.
295
-
296
- If your org has disabled Claude Desktop extension installs, install unpacked instead:
297
-
298
- 1. Clone the repo and run `npm ci && npm run build`.
299
- 2. Open Claude Desktop -> **Settings** -> **Extensions** -> **Advanced Settings** -> **Extension Developer** -> **Install Unpacked**.
300
- 3. Select the repo's root directory (the one containing `manifest.json`).
301
-
302
- To build the bundle yourself instead of downloading a release asset:
303
-
304
- ```bash
305
- npm ci
306
- npm run package:mcpb
307
- ```
308
-
309
- This produces `bambu-printer-mcp.mcpb` in the repo root using a pinned packaging tool. Packaging installs production dependencies in a temporary directory, retains licenses and source, excludes local credentials and models, and leaves your development dependencies intact.
310
-
311
- ### Recommended: use with codemode-mcp
312
-
313
- For any MCP server with a large tool surface, wrapping it behind [codemode-mcp](https://github.com/jx-codes/codemode-mcp) dramatically reduces token usage. Instead of exposing every tool definition to the model (which can consume tens of thousands of tokens per turn), codemode lets the agent write code against a two-tool interface (`search()` and `execute()`), loading only the tools it needs on demand.
314
-
315
- Anthropic and Cloudflare independently demonstrated this pattern reduces MCP token costs by up to 98%:
316
-
317
- - [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) (Anthropic)
318
- - [Code Mode: give agents an entire API in 1,000 tokens](https://blog.cloudflare.com/code-mode-mcp/) (Cloudflare)
319
-
320
- This applies to all MCP servers, not just this one.
321
-
322
- ---
323
-
324
- ## Enabling Developer Mode (Required)
325
-
326
- This MCP server communicates directly with your printer over your local network using MQTT and FTPS. For this to work, **Developer Mode** must be enabled on the printer. Without it, the printer will reject third-party LAN connections even if you have the correct access code.
327
-
328
- On H2D/H2-series firmware, the printer may stream `push_status` data without ever answering the legacy `get_version` handshake used by older libraries. This fork treats the live status stream as authoritative and does not require that extra ACK before considering the connection usable.
329
-
330
- Developer Mode is available on the following firmware versions and later:
331
-
332
- | Series | Minimum Firmware |
333
- |--------|-----------------|
334
- | P1 Series (P1P, P1S) | `01.08.02.00` |
335
- | X1 Series (X1C, X1E) | `01.08.03.00` |
336
- | A1 Series (A1, A1 Mini) | `01.05.00.00` |
337
- | H2D | `01.01.00.01` |
338
-
339
- If your firmware is older than these versions, update through Bambu Studio or the Bambu Handy app before proceeding.
340
-
341
- ### Step 1: Navigate to Network Settings
342
-
343
- On the printer's touchscreen, go to **Settings**, then select the **Network** (WLAN) page. You should see your WiFi network name, IP address, and the LAN Only Mode toggle.
344
-
345
- <p align="center">
346
- <img src="docs/images/p1s-network-settings.jpeg" width="400" alt="P1S network settings screen showing WLAN, LAN Only Mode, IP address, and Access Code" />
347
- </p>
348
-
349
- ### Step 2: Enable LAN Only Mode
350
-
351
- Toggle **LAN Only Mode** to **ON**. This enables direct local network communication protocols (MQTT on port 8883 and FTPS on port 990) that this server requires.
352
-
353
- **Important:** Enabling LAN Only Mode disconnects the printer from Bambu Lab's cloud services. The Bambu Handy mobile app will stop working while this mode is active. Bambu Studio and OrcaSlicer can still connect over LAN.
354
-
355
- ### Step 3: Enable Developer Mode
356
-
357
- Once LAN Only Mode is on, a **Developer Mode** option appears in the same settings menu. Toggle it **ON**. This allows third-party clients (like this MCP server) to authenticate and send commands over MQTT.
358
-
359
- ### Step 4: Note the Access Code
360
-
361
- The **Access Code** displayed on the network settings screen is your LAN access token. You will need this value for the `BAMBU_TOKEN` environment variable.
362
-
363
- <p align="center">
364
- <img src="docs/images/p1s-access-code.jpeg" width="400" alt="P1S network settings showing the Access Code field" />
365
- </p>
366
-
367
- The access code can be refreshed by tapping the circular arrow icon next to it. If you refresh it, any existing connections using the old code will be disconnected and you will need to update your configuration with the new code.
368
-
369
- ---
370
-
371
- ## Finding Your Bambu Printer's Serial Number and Access Token
372
-
373
- Two values are required to connect directly to a Bambu Lab printer over your local network: the printer's serial number and its LAN access token (the Access Code from Developer Mode setup above).
374
-
375
- ### Serial number
376
-
377
- The serial number is printed on a sticker on the back or underside of the printer. It typically follows one of these formats:
378
-
379
- - P1 Series: begins with `01P`
380
- - X1 Series: begins with `01X`
381
- - A1 Series: begins with `01A`
382
-
383
- You can also find it on the printer's touchscreen. Navigate to **Settings** and select the **Device Info** page:
384
-
385
- <p align="center">
386
- <img src="docs/images/p1s-device-info.jpeg" width="400" alt="P1S device info screen showing model name, serial number, AMS serial, and printing time" />
387
- </p>
388
-
389
- The **Printer** line shows your serial number. In Bambu Studio, you can also find it under Device > Device Management in the printer information panel.
390
-
391
- ### LAN access token
392
-
393
- The access token is the **Access Code** shown on the printer's network settings screen. It is separate from your Bambu Cloud account password. If you followed the [Developer Mode setup](#enabling-developer-mode-required) above, you already have this value.
394
-
395
- **P1 Series (P1P, P1S):**
396
- 1. On the printer touchscreen, go to Settings.
397
- 2. Select the Network / WLAN page.
398
- 3. The Access Code is displayed at the bottom of the screen.
399
-
400
- **X1 Series (X1C, X1E):**
401
- 1. On the printer touchscreen, go to Settings.
402
- 2. Select Network.
403
- 3. Enable LAN Only Mode and Developer Mode if not already on.
404
- 4. The Access Code appears on this screen.
405
-
406
- **A1 and A1 Mini:**
407
- 1. Open the Bambu Handy app on your phone.
408
- 2. Connect to your printer.
409
- 3. Navigate to Settings > Network.
410
- 4. The Access Code is shown here.
411
-
412
- Your printer must also be logged into a Bambu Cloud account for LAN mode to function. You can verify this on the cloud/account settings screen:
413
-
414
- <p align="center">
415
- <img src="docs/images/p1s-cloud-account.jpeg" width="400" alt="P1S cloud account screen showing logged-in user with Logout button" />
416
- </p>
417
-
418
- **Troubleshooting:** If the LAN Only Mode or Developer Mode options are not visible, your printer firmware is likely outdated. Update to the latest firmware version through Bambu Studio or the Bambu Handy app and try again.
182
+ </details>
419
183
 
420
- ---
184
+ <details>
185
+ <summary><strong>AMS (Automatic Material System) Setup</strong></summary>
421
186
 
422
187
  ## AMS (Automatic Material System) Setup
423
188
 
@@ -445,20 +210,20 @@ If you need to override the embedded mapping (for example, you swapped filament
445
210
 
446
211
  Each element in the array corresponds to a filament slot used in the print file, in the order they appear in the slicer. The value is the physical AMS slot number (0-based) where that filament is currently loaded. In the example above, the first filament in the print uses AMS slot 0, and the second uses AMS slot 2.
447
212
 
448
- The server pads this array to the 5 elements required by the printer's MQTT protocol. An `ams_mapping` of `[0, 2]` becomes `[0, 2, -1, -1, -1]` on the wire, where `-1` indicates unused positions.
213
+ Mapping is positional: each entry corresponds to a project filament, and `-1` means unused. H2/P2S project-file commands use project-length mapping plus a parallel `ams_mapping2`; other project-file routes retain at least five positions without truncating longer projects. Prefer `ams_slots` in plate filament order or `auto_match_ams: true` when you do not already have the full project mapping.
449
214
 
450
215
  ### Single-material prints
451
216
 
452
- For a single-material print (the most common case), the default mapping is `[-1, -1, -1, -1, 0]`, which tells the printer to pull filament from AMS slot 0. If your filament is in a different slot, specify it:
217
+ For a single-material plate, explicitly select its loaded tray. For example, use AMS slot 2:
453
218
 
454
219
  ```json
455
220
  {
456
221
  "three_mf_path": "/path/to/model.3mf",
457
- "ams_mapping": [2]
222
+ "ams_slots": [2]
458
223
  }
459
224
  ```
460
225
 
461
- This tells the printer to use AMS slot 2 for the single filament in the print.
226
+ This expands slot 2 into the correct project filament position. There is no universal fixed default mapping for every model and project.
462
227
 
463
228
  ### Printing without AMS
464
229
 
@@ -471,6 +236,8 @@ If you are using the direct-feed spool holder (no AMS attached) or want to bypas
471
236
  }
472
237
  ```
473
238
 
239
+ For H2 projects with declared filaments, also provide the required mapping; `use_ams: false` alone does not remove the firmware's mapping requirement. See [`print_3mf`](#print_3mf).
240
+
474
241
  ### Auto-match AMS by RFID
475
242
 
476
243
  For pre-sliced 3MFs that declare filament types, the `auto_match_ams` flag on `print_3mf` (or the standalone `resolve_3mf_ams_slots` dry-run tool) automatically resolves the required filaments against your live AMS inventory. The matcher works as follows:
@@ -501,19 +268,22 @@ Use `get_printer_filaments` for the parsed, enriched view (profile paths, displa
501
268
  "What filaments are loaded in my AMS right now?"
502
269
  ```
503
270
 
504
- ---
271
+ </details>
272
+
273
+ <details>
274
+ <summary><strong>Bambu Communication Notes (MQTT and FTP)</strong></summary>
505
275
 
506
276
  ## Bambu Communication Notes (MQTT and FTP)
507
277
 
508
278
  Bambu Lab printers do not use a conventional REST API. Instead, they expose two local protocols that this server uses directly:
509
279
 
510
- **MQTT (port 8883, TLS):** All printer commands and state reports flow over an MQTT broker running on the printer itself. The broker requires your serial number as the client ID and your access token as the password. Commands like starting a print, cancelling a job, and dispatching G-code lines are all MQTT publishes to the device topic. Status data is received by subscribing to the printer's report topic and requesting a `push_all` refresh. This implementation is based on community reverse engineering documented in the [OpenBambuAPI](https://github.com/Doridian/OpenBambuAPI) project.
280
+ **MQTT (port 8883, TLS):** All printer commands and state reports flow over an MQTT broker running on the printer itself. Authentication uses username `bblp` and your LAN access code; the serial number identifies the device topics. Commands like starting a print, cancelling a job, and dispatching G-code lines are all MQTT publishes to the device topic. Status data is received by subscribing to the printer's report topic and requesting a `push_all` refresh. This implementation is based on community reverse engineering documented in the [OpenBambuAPI](https://github.com/Doridian/OpenBambuAPI) project.
511
281
 
512
282
  **FTPS (port 990, implicit TLS):** File operations (upload and directory listing) use FTPS. The printer's SD card is accessible as a filesystem with directories including `cache/` (for 3MF and G-code print files), `timelapse/`, and `logs/`. Authentication uses the username `bblp` and your access token as the password.
513
283
 
514
284
  ### What this fork fixes
515
285
 
516
- Both this package and the parent project (`mcp-3D-printer-server`) include fixes for two protocol-level issues in the underlying `bambu-js` library.
286
+ This package works around two protocol-level issues in the underlying `bambu-js` library.
517
287
 
518
288
  **Bug 1: FTP double-path error in bambu-js.**
519
289
 
@@ -540,15 +310,15 @@ private async ftpUpload(host, token, localPath, remotePath): Promise<void> {
540
310
 
541
311
  The `bambu-js` library's project file command hardcodes `use_ams: true` and does not support the `ams_mapping` field at all. Without the fix, the mapping is a simple array of slot indices (e.g., `[0, 2]`), which does not match the OpenBambuAPI specification.
542
312
 
543
- According to the OpenBambuAPI spec, P1/A1/X1-series printers use a 5-element `ams_mapping` array where position `i` is the project filament index and the value is the AMS slot feeding that filament. For example, a single-filament print from AMS slot 0 sends `[0, -1, -1, -1, -1]`.
313
+ For the non-H2/P2S project-file route, this implementation retains at least five positions in the `ams_mapping` array where position `i` is the project filament index and the value is the AMS slot feeding that filament. For example, a single-filament print from AMS slot 0 sends `[0, -1, -1, -1, -1]`.
544
314
 
545
315
  This fork sends the `project_file` command directly via `bambu-node` (bypassing `bambu-js` entirely for print initiation) and constructs the mapping in the format the target firmware expects:
546
316
 
547
317
  ```typescript
548
- // P1/A1/X1-series: 5-element project lookup table
318
+ // Non-H2/P2S project_file: at least five entries; preserve longer projects
549
319
  ams_mapping = [0, -1, -1, -1, -1];
550
320
 
551
- // H2S/H2D/H2C: project-length lookup table + parallel ams_mapping2
321
+ // H2S/H2D/H2C/P2S: project-length lookup table + parallel ams_mapping2
552
322
  ams_mapping = [-1, 1, -1, -1];
553
323
  ams_mapping2 = [
554
324
  { ams_id: 255, slot_id: 255 },
@@ -562,7 +332,7 @@ The command payload also includes all required fields per the OpenBambuAPI spec:
562
332
 
563
333
  ### Verified print procedure (H2S, LAN-only, no client cert)
564
334
 
565
- This is the sequence that successfully started a print on an H2S running current (post-Jan 2025) firmware in LAN-only mode. It's documented here because several common approaches fail on this firmware, and this fork's transport is what makes it reliable.
335
+ This is the sequence that successfully started a print on an H2S in the original LAN-only test. It's documented here because several common approaches fail on this firmware, and this fork's transport is what makes it reliable.
566
336
 
567
337
  **Result:** print started in `RUNNING` state, printer accepted the MQTT `project_file` command, no client certificate was required. Authentication was plain `bblp` + LAN access code over TLS with `rejectUnauthorized: false`.
568
338
 
@@ -625,12 +395,15 @@ This is the sequence that successfully started a print on an H2S running current
625
395
  - No client X.509 certificate was needed. The earlier assumption that post-Jan 2025 firmware mandates mTLS on all models does not hold for the H2S in LAN mode — user/password over TLS is sufficient.
626
396
  - The MCP server's `ftpUpload` helper (basic-ftp with `secure: "implicit"` and a short idle timeout) performs the equivalent upload natively and is the preferred path when using the server itself; the curl form is the manual-debug equivalent.
627
397
 
628
- ---
398
+ </details>
399
+
400
+ <details>
401
+ <summary><strong>Available Tools</strong></summary>
629
402
 
630
403
  ## Available Tools
631
404
 
632
405
  <details>
633
- <summary><strong>Click to expand STL Manipulation Tools</strong></summary>
406
+ <summary><strong>STL Manipulation Tools</strong></summary>
634
407
 
635
408
  ### STL Manipulation Tools
636
409
 
@@ -734,7 +507,7 @@ Note: this works best on models with a clearly dominant flat face. Results on or
734
507
  </details>
735
508
 
736
509
  <details>
737
- <summary><strong>Click to expand Printer Control Tools</strong></summary>
510
+ <summary><strong>Printer Control Tools</strong></summary>
738
511
 
739
512
  ### Printer Control Tools
740
513
 
@@ -804,7 +577,7 @@ Capture a single JPEG frame from the printer's chamber camera. Read-only.
804
577
  Two transports are wired in, picked by `bambu_model`:
805
578
 
806
579
  - **TCP-on-6000** for **A1, A1 mini, P1S, P1P**. Native protocol per [OpenBambuAPI/video.md](https://github.com/Doridian/OpenBambuAPI/blob/main/video.md): TLS on port 6000, 80-byte auth packet (`bblp` + access token), repeating 16-byte frame header + JPEG payload.
807
- - **RTSP** for **X1, X1 Carbon, X1E, P2S** and **H2, H2S, H2D, H2C, H2D Pro**. Shells out to ffmpeg with `rtsps://bblp:<token>@<host>:322/streaming/live/1 -frames:v 1`. The H2 series wasn't documented in OpenBambuAPI's `video.md` but its firmware uses the same RTSP endpoint as X1 (verified live against an H2S, 2026-04-27).
580
+ - **RTSP** for **X1, X1 Carbon, X1E, P2S, X2D** and **H2, H2S, H2D, H2C, H2D Pro**. Shells out to ffmpeg with `rtsps://bblp:<token>@<host>:322/streaming/live/1 -frames:v 1`. The H2 series wasn't documented in OpenBambuAPI's `video.md` but its firmware uses the same RTSP endpoint as X1 (verified live against an H2S, 2026-04-27).
808
581
 
809
582
  **Requires ffmpeg in PATH** for the RTSP path. Install with `brew install ffmpeg` on macOS. Configure a trusted custom binary with the server-side `FFMPEG_PATH` environment variable, or set `MCP_ALLOW_EXECUTABLE_ARG=1` before using the `ffmpeg_path` tool argument. The TCP-on-6000 path uses native Node TLS and does not require ffmpeg.
810
583
 
@@ -839,6 +612,9 @@ A bare filename defaults to `cache/<filename>`. To target other directories pass
839
612
 
840
613
  ```json
841
614
  { "filename": "timelapse/2026-04-26_12-00.mp4", "confirm": true }
615
+ ```
616
+
617
+ ```json
842
618
  { "filename": "logs/printer.log", "confirm": true }
843
619
  ```
844
620
 
@@ -1054,13 +830,13 @@ To stop drying:
1054
830
 
1055
831
  #### print_3mf
1056
832
 
1057
- The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `.gcode.3mf` exported from Bambu Studio** — see [docs/SLICING.md](./docs/SLICING.md). This tool handles the complete workflow:
833
+ The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `.gcode.3mf` exported from FULU OrcaSlicer-bambulab, OrcaSlicer, or Bambu Studio** — see [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md). This tool handles the complete workflow:
1058
834
 
1059
835
  1. Checks whether the 3MF contains embedded G-code (`Metadata/plate_<n>.gcode` entries).
1060
- 2. If no G-code is found, attempts to auto-slice via the configured slicer. This fallback is unreliable in practice (stale profiles, leftover multi-filament declarations) — prefer pre-slicing in Bambu Studio.
836
+ 2. If no G-code is found, attempts to auto-slice via the configured slicer. Profile preparation or slicing failures stop the operation before upload. See the slicing guide for tested CLI versions and combinations.
1061
837
  3. Parses the sliced 3MF to extract the correct plate file and compute its MD5 hash.
1062
- 4. Also parses `Metadata/project_settings.config` to read AMS mapping embedded by Bambu Studio.
1063
- 5. Uploads the 3MF to the printer's `cache/` directory via FTPS using `basic-ftp` directly (avoiding the bambu-js double-path bug).
838
+ 4. Reads slicer metadata and any explicit AMS selection to build the filament mapping.
839
+ 5. Uploads via `basic-ftp` to the model-specific location: SD root for H2/full-size A1, `cache/` for P1/X1/A1 mini/P2S. X2D direct printing stops before upload.
1064
840
  6. Sends the correct MQTT print command for the target printer family. For H2S/H2D/H2C that means `project_file` with project-length `ams_mapping`, parallel `ams_mapping2`, and H2-compatible calibration flags.
1065
841
 
1066
842
  ```json
@@ -1080,7 +856,7 @@ The primary tool for starting a Bambu print. **Recommended input: a pre-sliced `
1080
856
  }
1081
857
  ```
1082
858
 
1083
- `bambu_model` is **required** -- it ensures the slicer generates G-code for the correct printer. Using the wrong model can cause the bed to crash into the nozzle. If `bambu_model` is not provided in the tool call and `BAMBU_MODEL` is not set in the environment, the server will ask you interactively via MCP elicitation (if your client supports it) or return a clear error.
859
+ `bambu_model` is **required** for model-specific routing and preset selection. It does not by itself validate pre-sliced G-code. BambuStudio, FULU, and Orca CLI preparation additionally require the exact model/nozzle machine preset and reject incomplete profiles. Using the wrong model can damage hardware. If `bambu_model` is not provided in the tool call and `BAMBU_MODEL` is not set in the environment, the server will ask you interactively via MCP elicitation (if your client supports it) or return a clear error.
1084
860
 
1085
861
  `bed_type` defaults to `textured_plate` if omitted. `ams_slots` is the preferred override input; `ams_mapping` remains the raw escape hatch. On AMS-equipped H2 printers, `use_ams: false` does not suppress mapping lookup if the sliced file declares filaments. If no mapping is provided for an H2 pre-sliced job with declared filaments, the server fails before sending; pass explicit `ams_slots`, raw `ams_mapping`, or `auto_match_ams: true`.
1086
862
 
@@ -1088,6 +864,20 @@ Set `auto_match_ams: true` to match the sliced 3MF's `tray_info_idx` values agai
1088
864
 
1089
865
  Layer height, nozzle temperature, and other slicer parameters cannot be overridden via this tool -- they are baked into the 3MF's G-code at slice time. Apply those settings in your slicer before generating the 3MF.
1090
866
 
867
+ For the optional FULU bridge, set `connection_mode: "bambu_network"` and explicitly choose `connection_type: "cloud"` or `"lan"`; see [FULU setup](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md). A successful command submission is not proof that the printer accepted it: inspect printer state, HMS errors, and the printer itself.
868
+
869
+ #### bambu_network_bridge_status
870
+
871
+ Inspect the configured FULU bridge without starting it using `{}`. Use `{"connect": true}` to launch the host, handshake, and initialize an agent. See [bridge probes](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#probe-without-printing) for interpreting the result.
872
+
873
+ #### bambu_network_call
874
+
875
+ Call a runtime method such as `{"method": "net.is_user_login", "payload": {}}`. The default injects the initialized agent; use `with_agent: false` for `bridge.handshake`. Raw methods can mutate runtime or printer state; use the method contract from your installed FULU build.
876
+
877
+ #### print_3mf_bambu_network
878
+
879
+ Submit a sliced project through FULU's separately configured networking runtime. `connection_type` defaults to `cloud`; LAN bridge jobs also require a printer IP and access code. `bambu_model` and a device ID are required. See [print examples and AMS requirements](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#print-through-the-bridge). A zero bridge return code confirms submission, not a physical print or direct X2D support.
880
+
1091
881
  #### resolve_3mf_ams_slots
1092
882
 
1093
883
  Dry-run the AMS match without uploading or starting a print. The tool reads `Metadata/plate_<n>.json` and `Metadata/slice_info.config`, then compares required `tray_info_idx` values against live AMS trays.
@@ -1156,11 +946,11 @@ If the project does not match those assumptions, the tool fails fast with a stru
1156
946
  </details>
1157
947
 
1158
948
  <details>
1159
- <summary><strong>Click to expand Slicing Tools</strong></summary>
949
+ <summary><strong>Slicing Tools</strong></summary>
1160
950
 
1161
951
  ### Slicing Tools
1162
952
 
1163
- > **Note:** the verified workflow is to slice in Bambu Studio (GUI) and feed the resulting `.gcode.3mf` to `print_3mf`. The CLI-driven slicing tools below (`slice_stl`, `slice_with_template`) work but are sensitive to profile drift and are not the recommended path for production prints. See [docs/SLICING.md](./docs/SLICING.md).
953
+ > **Note:** the verified workflow is to slice in Bambu Studio (GUI) and feed the resulting `.gcode.3mf` to `print_3mf`. The CLI-driven slicing tools below (`slice_stl`, `slice_with_template`) work but are sensitive to profile drift and are not the recommended path for production prints. See [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md).
1164
954
 
1165
955
  #### list_templates
1166
956
 
@@ -1213,24 +1003,25 @@ This uses the named template as the slicing profile source and still supports li
1213
1003
 
1214
1004
  #### slice_stl
1215
1005
 
1216
- Slice an STL or 3MF file using an external slicer and return the path to the output file. The output is a sliced 3MF (for BambuStudio and OrcaSlicer) or a G-code file (for PrusaSlicer, Cura, Slic3r).
1006
+ Slice an STL or 3MF file using an external slicer and return the path to the output file. The output is a sliced 3MF (for BambuStudio, OrcaSlicer, and FULU OrcaSlicer-bambulab) or a G-code file (for PrusaSlicer, Cura, Slic3r).
1217
1007
 
1218
1008
  ```json
1219
1009
  {
1220
1010
  "stl_path": "/path/to/model.stl",
1221
1011
  "slicer_type": "bambustudio",
1222
- "slicer_path": "/Applications/BambuStudio.app/Contents/MacOS/BambuStudio",
1223
- "slicer_profile": "/path/to/profile.ini"
1012
+ "bambu_model": "p1s"
1224
1013
  }
1225
1014
  ```
1226
1015
 
1227
- `slicer_type` options: `bambustudio`, `orcaslicer`, `prusaslicer`, `cura`, `slic3r`. When omitted, the value from the `SLICER_TYPE` environment variable is used (default: `bambustudio`).
1016
+ `slicer_type` options: `bambustudio`, `orcaslicer`, `orcaslicer-bambulab` (FULU), `prusaslicer`, `cura`, `slic3r`. Aliases include `fulu-orca` and `orca-studio`. When omitted, the value from the `SLICER_TYPE` environment variable is used (default: `bambustudio`).
1017
+
1018
+ **FULU/Orca CLI safety:** from 1.1.11, these backends require the exact model/nozzle preset from the selected installation and stop on profile preparation failures. A process override cannot bypass that gate. See [configuration and validation limits](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md#fulu-and-orca-cli-safety-limit).
1228
1019
 
1229
1020
  `slicer_path` and `slicer_profile` fall back to the `SLICER_PATH` and `SLICER_PROFILE` environment variables when omitted. Per-call `slicer_path` overrides require `MCP_ALLOW_EXECUTABLE_ARG=1`.
1230
1021
 
1231
1022
  You can provide either `template_3mf_path` or `template_name` when you want to slice from a saved template. `template_name` resolves through the local template registry directory configured for the server.
1232
1023
 
1233
- For printing on a Bambu printer, the recommended workflow is: slice with `bambustudio` to get a sliced 3MF, then pass that output path to `print_3mf`.
1024
+ For printing on a Bambu printer, the recommended workflow is: export a sliced 3MF from your selected Bambu-compatible slicer, then pass that output path to `print_3mf`.
1234
1025
 
1235
1026
  #### BambuStudio Slicer Options
1236
1027
 
@@ -1278,12 +1069,12 @@ When `print_3mf` detects an unsliced 3MF and auto-slices it, these defaults are
1278
1069
  - `min_save: true` -- smaller output for faster FTP uploads to the printer
1279
1070
  - `skip_modified_gcodes: true` -- strips custom gcodes from other users' profiles
1280
1071
 
1281
- These defaults keep you safe when printing downloaded models. When calling `slice_stl` directly, you have full control over every flag.
1072
+ These defaults reduce stale-profile problems; inspect downloaded models and their slice preview before printing. When calling `slice_stl` directly, you have full control over every flag.
1282
1073
 
1283
1074
  </details>
1284
1075
 
1285
1076
  <details>
1286
- <summary><strong>Click to expand Advanced Tools</strong></summary>
1077
+ <summary><strong>Advanced Tools</strong></summary>
1287
1078
 
1288
1079
  ### Advanced Tools
1289
1080
 
@@ -1353,7 +1144,10 @@ configuration is an error when execution is requested. Per-call legacy
1353
1144
 
1354
1145
  </details>
1355
1146
 
1356
- ---
1147
+ </details>
1148
+
1149
+ <details>
1150
+ <summary><strong>Available Resources</strong></summary>
1357
1151
 
1358
1152
  ## Available Resources
1359
1153
 
@@ -1369,7 +1163,10 @@ Resources follow the MCP resource protocol and can be read by calling `ReadResou
1369
1163
 
1370
1164
  **Example:** To read the status of the default printer, use URI `printer://192.168.1.100/status`. The host segment must match a configured printer IP; the server uses `PRINTER_HOST` if the default URI template is used.
1371
1165
 
1372
- ---
1166
+ </details>
1167
+
1168
+ <details>
1169
+ <summary><strong>Example Commands for Claude</strong></summary>
1373
1170
 
1374
1171
  ## Example Commands for Claude
1375
1172
 
@@ -1402,7 +1199,8 @@ After connecting the MCP server in Claude Desktop or Claude Code, you can ask Cl
1402
1199
  - "Upload bracket.3mf to the printer and start printing with AMS slots 0 and 1."
1403
1200
  - "Print my_model.3mf with bed leveling enabled and vibration calibration off."
1404
1201
  - "Upload this 3MF without printing it yet."
1405
- - "Slice model.stl with BambuStudio and then print the result."
1202
+ - "Use FULU OrcaSlicer-bambulab to prepare this model, then show me the sliced output before printing."
1203
+ - "Probe the FULU BambuNetwork bridge without starting a print."
1406
1204
 
1407
1205
  ### STL manipulation
1408
1206
 
@@ -1421,27 +1219,33 @@ After connecting the MCP server in Claude Desktop or Claude Code, you can ask Cl
1421
1219
  - "Take this unsliced 3MF, slice it with BambuStudio, and print the result."
1422
1220
  - "Scale this part to 80% of its size, lay it flat, and start a print."
1423
1221
 
1424
- ---
1222
+ </details>
1223
+
1224
+ <details>
1225
+ <summary><strong>Bambu Lab Printer Limitations</strong></summary>
1425
1226
 
1426
1227
  ## Bambu Lab Printer Limitations
1427
1228
 
1428
1229
  Understanding these constraints will help you avoid frustrating errors and set appropriate expectations.
1429
1230
 
1430
- 1. **Printable 3MF required for print_3mf.** The `print_3mf` tool expects a sliced 3MF containing at least one `Metadata/plate_<n>.gcode` entry. If you pass an unsliced 3MF (one exported from a CAD tool without slicing), the server will attempt to auto-slice it using the configured slicer — but this fallback is brittle and the recommended workflow is to pre-slice in Bambu Studio and pass the resulting `.gcode.3mf`. See [docs/SLICING.md](./docs/SLICING.md) for the full procedure.
1231
+ 1. **Printable 3MF required for print_3mf.** The `print_3mf` tool expects a sliced 3MF containing at least one `Metadata/plate_<n>.gcode` entry. If you pass an unsliced 3MF (one exported from a CAD tool without slicing), the server attempts auto-slicing. BambuStudio, FULU, and Orca CLI paths require the matching machine preset and complete profile preparation; any inspection or slicing failure stops before upload. For a previewable workflow, pre-slice in FULU OrcaSlicer-bambulab, OrcaSlicer, or Bambu Studio and pass the resulting `.gcode.3mf`. See [slicing guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md) for the full procedure.
1431
1232
 
1432
1233
  2. **Layer height, temperature, and slicer settings are baked in.** The `project_file` MQTT command tells the printer which plate to run. It does not support overriding layer height, temperature targets, infill percentage, or other slicing parameters at print time. These must be set in your slicer before generating the 3MF.
1433
1234
 
1434
- 3. **G-code and 3MF jobs use different command paths.** `start_print_job` sends a `GCodeFileCommand` over MQTT and is intended only for plain G-code files stored in the `cache/` directory. `.3mf` files must go through `print_3mf`, which sends the `project_file` command with plate selection, MD5 verification, and AMS mapping. Mixing these up will result in the printer either ignoring the command or displaying an error.
1235
+ 3. **G-code and 3MF jobs use different command paths.** `start_print_job` sends a `GCodeFileCommand` over MQTT and is intended only for plain G-code files stored in the `cache/` directory. Sliced 3MF files must go through `print_3mf`, which selects the model-specific command and upload location. See the [routing table](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/SLICING.md#firmware-routing-handled-internally). Mixing these up will result in the printer either ignoring the command or displaying an error.
1435
1236
 
1436
1237
  4. **Temperature commands depend on printer state.** `set_temperature` dispatches M104 or M140 G-code via MQTT. Whether the printer accepts these commands depends on its current firmware version and operational state. Some printer states (such as the idle screen with AMS management open) may ignore or queue the commands.
1437
1238
 
1438
- 5. **Real-time status has latency.** `get_printer_status` sends a `push_all` MQTT request and waits up to 1.5 seconds for a response before reading cached state. If the printer is not responding quickly (busy, sleeping, or transitioning states), you may see slightly stale data. There is no persistent event subscription in this server -- each status call is a fresh request.
1239
+ 5. **Status and command submission are separate evidence.** Local MQTT connections are reused and status is read from received printer reports. Reports can lag during startup, sleep, or state transitions. Inspect HMS errors and the printer's actual state after submitting a job; a tool's success response is not physical-print confirmation.
1439
1240
 
1440
- 6. **LAN mode required.** All operations require the printer to be on the same local network as the machine running this server. Cloud-only or remote access setups are not supported. If your printer is connected only via Bambu Cloud and LAN mode is disabled, connection will fail.
1241
+ 6. **Network requirements depend on the path.** Direct MQTT/FTPS tools require local reachability and compatible LAN/Developer Mode settings. FULU bridge cloud jobs use BambuNetwork and require its runtime, internet access, and authentication. Standard status, camera, file, and control tools remain local; bridge printing does not turn them into cloud tools.
1441
1242
 
1442
1243
  7. **Self-signed TLS certificate.** The printer's FTPS server uses a self-signed certificate. The `basic-ftp` client is configured with `rejectUnauthorized: false` to accept it. This is standard for local network Bambu connections but assumes a trusted local network environment.
1443
1244
 
1444
- ---
1245
+ </details>
1246
+
1247
+ <details>
1248
+ <summary><strong>General Limitations and Considerations</strong></summary>
1445
1249
 
1446
1250
  ## General Limitations and Considerations
1447
1251
 
@@ -1467,7 +1271,10 @@ STL manipulation tools load the entire mesh into memory as Three.js geometry. Fo
1467
1271
  - FTPS uploads for large 3MF files (multi-plate prints, high-detail models) may take 15 to 60 seconds depending on your local network speed.
1468
1272
  - MQTT connections are pooled by `host + serial` key. The first call to any printer tool in a session establishes the MQTT connection; subsequent calls reuse it. If the connection drops (printer power cycled, network interruption), the next call will reconnect automatically.
1469
1273
 
1470
- ---
1274
+ </details>
1275
+
1276
+ <details>
1277
+ <summary><strong>License</strong></summary>
1471
1278
 
1472
1279
  ## License
1473
1280
 
@@ -1475,6 +1282,15 @@ GPL-2.0. See [LICENSE](./LICENSE) for the full text.
1475
1282
 
1476
1283
  This project is a fork of [mcp-3D-printer-server](https://github.com/DMontgomery40/mcp-3D-printer-server) by David Montgomery, also GPL-2.0.
1477
1284
 
1285
+ </details>
1286
+
1287
+ <details>
1288
+ <summary><strong>Acknowledgements</strong></summary>
1289
+
1478
1290
  ## Acknowledgements
1479
1291
 
1292
+ Thank you to **[FULU Foundation](https://www.fulu.org/), [Louis Rossmann](https://www.youtube.com/watch?v=1jhRqgHxEP8), and the [OrcaSlicer-bambulab community](https://github.com/FULU-Foundation/OrcaSlicer-bambulab)** for advancing user choice and interoperability. Our support for open-source tools, repair rights, and printing without Bambu's software or cloud is a project priority. See the [FULU setup guide](https://github.com/DMontgomery40/bambu-printer-mcp/blob/main/docs/FULU.md) and [contributor credits](./CONTRIBUTORS.md).
1293
+
1480
1294
  Some printer command surfaces and workflow priorities were informed by [Bambuddy](https://github.com/maziggy/bambuddy), an AGPL-3.0 Bambu Lab printer management project. This project does not vendor Bambuddy code.
1295
+
1296
+ </details>