Metadata-Version: 2.5
Name: unofficial-bambu-mcp
Version: 0.3.0
Summary: Unofficial MCP server to build, edit, slice, check and calibrate Bambu Studio projects (.3mf) from an AI assistant.
Project-URL: Homepage, https://github.com/danielefinocchiaro/unofficial-bambu-mcp
Project-URL: Documentation, https://github.com/danielefinocchiaro/unofficial-bambu-mcp/tree/main/docs
Project-URL: Issues, https://github.com/danielefinocchiaro/unofficial-bambu-mcp/issues
Project-URL: Changelog, https://github.com/danielefinocchiaro/unofficial-bambu-mcp/blob/main/CHANGELOG.md
Author: Daniele Finocchiaro
License-Expression: MIT
License-File: LICENSE
Keywords: 3d printing,3mf,bambu lab,bambu studio,calibration,claude,mcp,slicer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Printing
Requires-Python: >=3.10
Requires-Dist: fonttools>=4.40
Requires-Dist: manifold3d>=2.4
Requires-Dist: mcp>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=10
Requires-Dist: shapely>=2.0
Description-Content-Type: text/markdown

# unofficial-bambu-mcp

<!-- mcp-name: io.github.danielefinocchiaro/unofficial-bambu-mcp -->

[![ci](https://github.com/danielefinocchiaro/unofficial-bambu-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/danielefinocchiaro/unofficial-bambu-mcp/actions/workflows/ci.yml)
![python](https://img.shields.io/badge/python-3.10%2B-blue)
![license](https://img.shields.io/badge/license-MIT-green)

> **Unofficial community project.** Not affiliated with, endorsed by or supported by Bambu Lab.
> "Bambu Lab", "Bambu Studio", "Bambu Connect" and "Bambu Handy" are trademarks of their respective owners.

An [MCP](https://modelcontextprotocol.io) server that lets an AI assistant (Claude Code, Claude Desktop or any
MCP client) **build, edit, slice, check and calibrate Bambu Studio projects**, using the official Bambu Studio
you already have installed, and **read your printer's status** on the local network.

You talk, it does the slicer work:

- *"New P1S project: a 20 mm cube and the text 'DANI' in white on a black 2 mm tag."*
- *"Open `~/Downloads/Gnome 3 Color.3mf`, add a plate with two more gnomes, then convert it for the A1 mini."*
- *"I have eSUN PLA Basic in AMS slot 2: make a preset for it and the test prints to calibrate it."*
- *"Before I start this 20-hour plate: which parts are likely to come off?"*
- *"A pin came off at layer 4 and I skipped it: make me a project to reprint just that pin, with a brim."*
- *"How is the print going? Which spool is it feeding from?"*

![A session: a project from scratch, a print risk fixed, slicing, a temperature tower, the print file](https://github.com/danielefinocchiaro/unofficial-bambu-mcp/raw/main/docs/demo.gif)

<sub>A real session, sped up: every tool call, result and image comes from the server through MCP; only the requests
are written for the demo ([scripts/make_demo.py](scripts/make_demo.py)).</sub>

## What it can do

| Area | What you can do |
|---|---|
| Projects | Create a project, or **open any .3mf** saved by Bambu Studio (2.x and older 1.6/1.7 files) or downloaded from MakerWorld / Printables: painted colors, modifiers, per-object settings, instances and plates are kept. Save without ever overwriting. |
| Printers | All 14 Bambu Lab printers of Bambu Studio 2.8, tested end to end (project, arrange, slice, print file): A1 mini, A1, A2L, P1P, P1S, P2S, X1, X1 Carbon, X1E, H2S and the **two-nozzle H2D, H2D Pro, H2C and X2D** (filaments go to a nozzle automatically, as Bambu Studio does). **Switch printer** and objects are re-arranged for the new bed. New projects use the build plate you picked in Bambu Studio for that printer. |
| Filaments | AMS slots with preset and color, your own user presets included. `use_ams_filaments` takes what is loaded in the AMS right now. |
| Plates & objects | Import STL, OBJ, 3MF; boxes, cylinders, cones, spheres and **text** (with a base in another color). Move, rotate, scale, **mirror**, **lay flat**, **auto orient** (least support, enough on the bed), duplicate, **fill the plate with copies**, **split** into objects or parts, **merge** objects into one, **mesh boolean** (holes, unions, intersections) with painted colors kept, filament per object or part, per-object settings, closed-solid check. Object ids stay the same while you work. |
| Arranging | `arrange` by the real outline seen from above, brim and brim ears included, so shapes nest (Bambu Studio's own arrange uses convex hulls). Gap, rotation steps, one material per plate, calibration corner, align to Y, prime tower corner kept free; one plate, chosen objects or all; "put them in N plates" evenly or as few as possible, and if they do not fit nothing moves and it says what is left over. |
| Cutting | `cut_object` on any plane, with **connectors** like Bambu Studio's Cut tool: a **plug** (peg and hole with clearance), **dowels** (holes in both pieces and separate pins) or a **dovetail**; round, square or hexagonal, straight or tapered, placed automatically or where you say, made shallower where a piece is thin. The pieces are laid out to print: the peg always points up. |
| Modifiers | Box or **round** parts: modifiers with their own settings ("the top 5 mm at 100 % infill"), negative parts (holes for magnets and screws), support blockers and enforcers. |
| Settings | Read or change any Bambu Studio setting, per filament slot when it applies, with a warning when a value cannot apply (e.g. a textured-plate temperature on a smooth plate). |
| Presets | Save the project's changes as Bambu Studio **user presets**: filament (`save_filament_preset`), **process** and **printer**; or change one of your presets directly (`edit_preset`), list, rename and delete them, with a backup copy each time. Values are checked and written the way Bambu Studio does (one per nozzle variant where it applies), and changes are stamped for Bambu Studio's cloud sync. Presets that are in your Bambu cloud can only be deleted from Bambu Studio: the answer says how. |
| Text & logos | `add_relief`: text or an **SVG logo** on any face of an object, raised (in another color if you like) or engraved, **following curved surfaces** too (the surface under it is measured on a fine grid and the shape is wrapped on it, keeping its size along the surface). `add_shape('svg')`: a logo as an object, on a base in another color. SVG paths, shapes, transforms, fill rules and strokes are read. |
| Measuring | `measure_object`: size and place, each part's volume and surface, the area on the bed, the **clearance between the pieces** of a print-in-place model, **walls thinner than the nozzle line** (where and at which height), and the cross-section at any height: how long and thick a bar is, how wide a hole is. `measure_between`: the gap between two objects or parts, centers, overlap. Dense meshes are measured on a copy within 0.005 mm (2.4 M triangles in about 9 s). |
| Height ranges & plates | `set_height_range`: settings for a band of an object's height, like Bambu Studio's Height range modifier: 100 % infill at the bottom, **finer layers** where the details are (variable layer height), **another filament for a band** (color by height). Variable layer heights and ranges in opened files are kept. `set_plate_settings`: build plate, print sequence (by object), first-layer filament order, spiral vase and prime tower place per plate. |
| Painting | `paint_object`: colors, supports (or no supports), seams and fuzzy skin on a height band and/or the faces looking one way (top, sides, overhangs...), with sharp edges. Checked on the sliced G-code: a color band changes filament at its edges, painted supports appear where painted. |
| Purge volumes | `get_purge_volumes` / `set_purge_volumes`: the purge between each pair of slots and the multiplier, as in Bambu Studio's dialog; the values in opened files are kept. |
| Slicing | Bambu Studio command line: time, grams and **cost** per filament, filament changes, pauses, layers and warnings per plate. Empty plates are skipped. |
| Previews | Images of a plate (iso or top, zoom, painted colors, **object labels**) and of any **sliced layer**, so the assistant checks its own work. |
| Print risks | `check_print_risks`: tall and narrow parts, parts standing on a tiny or narrow footing without a brim, filaments not meant for the build plate, tall parts sharing a long plate, a full brim on a print-in-place model whose joints it would weld. |
| Brim ears | `add_brim_ears`: small round brims only on the thin tips (fingers, toes) of print-in-place and articulated models, placed automatically away from joint gaps and other pieces, or where you say. Bambu Studio's *Painted* brim, checked on the sliced first layer. |
| Reprints | `reprint_objects`: a new project with only the parts that failed, same settings, with a brim. |
| Calibration | **Temperature tower**, **flow rate test** (pass 1 and 2), **pressure advance tower**, **max volumetric speed test**, **retraction test**, **VFA test** (wall speeds), **first-layer test**, for any filament. Save the result as a **Bambu Studio filament preset**: a new filament gets its own id, like Bambu Studio's *Create Filament*, so you can pick it for an AMS slot; updating it later keeps that id. |
| Layer actions | **Pause** at a height (magnets, nuts), **filament change** at a height, or any G-code at a height. |
| Printing | `send_to_printer` makes the print file of a plate and opens it in **Bambu Studio** (or **Bambu Connect**) ready to print: you check the AMS mapping and press Print. |
| Developer Mode (LAN farms) | For printers in LAN-only mode with Developer Mode, where Bambu firmware accepts commands from other programs: `send_to_printer(via='lan')` uploads the plate and **starts the print**, `skip_objects` skips parts of the running print, `ams_load` / `ams_unload` move filament. Each asks first: the first call sends nothing and gives a code to confirm with. In normal cloud mode the printer refuses them and the answer says so. |
| Printer status | `printer_status` (read only, local network): state, progress, temperatures, AMS trays with humidity, skipped objects, and warnings (unknown spool being fed, sport speed on a long print, a reading that looks old). |
| Camera & SD card | `printer_camera`: a picture of the plate right now, so the assistant sees how the print is going. `printer_files` / `download_printer_file`: timelapses (with their last frame) and past print files. `delete_printer_files`: free space on the SD card, only after you confirm the exact list. Works in cloud mode. |

All 87 tools with their parameters: [docs/TOOLS.md](docs/TOOLS.md).

## Tested on

**Real hardware**: macOS, Bambu Studio 2.8.2, a **P1S with two AMS units**, in normal cloud mode:

- every tool through a real MCP client, on projects made from scratch and on MakerWorld / Printables downloads
  (painted 6-color models, multi-part assemblies, 3-plate projects, files from Bambu Studio 1.6 and 1.7);
- printed: temperature towers and flow tests for two third-party filaments (eSUN PLA Basic black and white), whose
  presets were made and tuned through the server; the print hand-off to Bambu Studio; live status during prints.

The pressure advance tower, the max volumetric speed test and the retraction test are checked by slicing (the G-code
is inspected) but have not been printed yet.

**Windows and Linux**: on every change to `main`, CI installs Bambu Studio 2.8.2 (the portable zip on Windows, the
AppImage on Debian 13) and runs the whole test suite, slicing and print files included, plus a smoke run. Unit tests
run on Windows, macOS and Linux with Python 3.10 and 3.13. On Linux the AppImage takes FFmpeg 7 and WebKitGTK 4.1
from the system (Debian 13, Ubuntu 24.10 or newer); set `BAMBU_STUDIO_EXE` if Bambu Studio is somewhere else.

**Printers**: all 14 Bambu Lab printers of Bambu Studio 2.8 go through the MCP from a new project to a print file
(A1 mini, A1, A2L, P1P, P1S, P2S, X1, X1 Carbon, X1E, H2S, H2C, H2D, H2D Pro, X2D); only the P1S has printed.
The Developer Mode tools were checked against a printer in cloud mode (refused, with the right answer) but never
started a print on one in Developer Mode.

## Printing and your printer

Bambu firmware (2025 and later) accepts commands from other programs only when the printer is in **LAN-only mode
with Developer Mode** on, which turns off the cloud and Bambu Handy. In normal cloud mode it refuses them, so this
server:

- **reads** the printer status (allowed in cloud mode), with the LAN access code Bambu Studio already saved;
- **hands the print over** to Bambu Studio or Bambu Connect, where you press Print;
- does **not** start prints, set AMS slots or skip objects in cloud mode: you do that in Bambu Studio, Bambu Handy or
  on the printer. For printers in LAN-only mode with Developer Mode (print farms) it can, always after you confirm
  with the code it gives (see the Developer Mode row above).

More in [docs/printing.md](docs/printing.md).

## Quick start

Requirements: Python 3.10+, [uv](https://docs.astral.sh/uv/) and Bambu Studio.

```bash
git clone https://github.com/danielefinocchiaro/unofficial-bambu-mcp
cd unofficial-bambu-mcp && uv sync
```

It is a standard MCP server (stdio), so any MCP client that runs local servers can use it. It was developed and
tested with Claude Code; the other clients below take the same command in their own config file.

**Claude Code**

```bash
claude mcp add bambu -- uv run --directory /path/to/unofficial-bambu-mcp unofficial-bambu-mcp
```

**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json`), **Windsurf**
(`~/.codeium/windsurf/mcp_config.json`), **Gemini CLI** (`~/.gemini/settings.json`):

```json
{
  "mcpServers": {
    "bambu": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unofficial-bambu-mcp", "unofficial-bambu-mcp"]
    }
  }
}
```

**OpenAI Codex CLI** (`~/.codex/config.toml`):

```toml
[mcp_servers.bambu]
command = "uv"
args = ["run", "--directory", "/path/to/unofficial-bambu-mcp", "unofficial-bambu-mcp"]
```

**VS Code** (GitHub Copilot agent mode, `.vscode/mcp.json`):

```json
{ "servers": { "bambu": { "type": "stdio", "command": "uv",
  "args": ["run", "--directory", "/path/to/unofficial-bambu-mcp", "unofficial-bambu-mcp"] } } }
```

The ChatGPT app only connects to remote MCP servers, and this one has to run on the computer with Bambu Studio.

Then ask: *"What version of Bambu Studio do I have, and which printers can you use?"*

### Configuration (optional)

| Variable | Default | Meaning |
|---|---|---|
| `UBMCP_DIR` | `~/Documents/unofficial-bambu-mcp` | Where projects, sliced files and print files are saved |
| `BAMBU_STUDIO_EXE` | auto-detected | Path of the Bambu Studio executable |
| `BAMBU_STUDIO_DATA` | auto-detected | Bambu Studio data folder (with `system/` and `user/`) |
| `BAMBU_STUDIO_RESOURCES` | auto-detected | Bambu Studio resources folder (with `profiles/`), for unusual Linux installs |
| `UBMCP_PRESET_BACKUPS` | `~/.config/unofficial-bambu-mcp/preset-backups` | Where a copy of a user preset goes before it is changed, renamed or deleted |
| `BAMBU_PRINTER_SERIAL`, `BAMBU_PRINTER_ACCESS_CODE`, `BAMBU_PRINTER_IP` | from Bambu Studio | Printer for `printer_status`, if you do not want it read from Bambu Studio |

## How it works

Bambu Studio has no plugin or scripting API. This server works on the **project file** (.3mf, the format Bambu
Studio saves) and calls the **Bambu Studio command line** to slice. Presets are read from your installation and
flattened the way the app does. Details in [docs/how-it-works.md](docs/how-it-works.md).

- **In sync with the app.** `open_in_bambu_studio` shows a project in the app; if you change it there and save,
  the server re-reads it on the next command (and tells you if both sides changed).
- **Safe with your files.** Nothing is ever overwritten: saving adds `-2`, `-3`... and opened files are read as a
  copy. Changing, renaming or deleting one of your presets keeps a backup copy first.
- **Light.** numpy, shapely, manifold3d, fonttools and Pillow. No Bambu profile is shipped with this repository:
  presets come from your installation (the server only carries default values for settings that presets leave out).
- **Your printer, your call.** The LAN access code is read from Bambu Studio when needed and never copied
  anywhere. See [SECURITY.md](SECURITY.md).

## Guides

- [Calibrating a filament](docs/calibration.md), step by step, with what to look at on each test print
- [Printing and printer status](docs/printing.md)
- [Troubleshooting](docs/troubleshooting.md)
- [How it works](docs/how-it-works.md)
- [Driving a closed slicer from an AI assistant](docs/paper.md): a technical write-up of the design and the tests

## Limitations

- Two-nozzle printers (H2D, H2C, X2D): filaments go to a nozzle automatically, as in Bambu Studio's default;
  choosing the nozzle of each filament by hand is not there yet.
- The printer camera works with P1 and A1 printers (X1 and H2 stream over RTSP, not supported yet).
- First-layer tests do not keep painted colors.
- Bambu Studio re-slices a project when it opens it; to see a plate sliced and ready to print in the app, use
  `send_to_printer`.

## Roadmap

- A package on PyPI (`uvx unofficial-bambu-mcp`)
- Mesh simplification and repair; the nozzle of each filament on two-nozzle printers; X1/H2 camera
- A live bridge inside the slicer, to be proposed to OrcaSlicer and Bambu Studio

## Contributing and support

Bug reports, ideas and pull requests: [GitHub Issues](../../issues). Include your OS, Bambu Studio version,
printer and, if you can, the .3mf that fails. See [CONTRIBUTING.md](CONTRIBUTING.md).

Author: Daniele Finocchiaro — [danielefinocchiaro.com](https://danielefinocchiaro.com). If it saves you prints
and time: [buy me a coffee](https://buymeacoffee.com/danifinocchiaro).

## License

[MIT](LICENSE) for this code. Bambu Studio profiles are read from your installation and are not redistributed.
