# Bambu Studio MCP

An [MCP](https://modelcontextprotocol.io) server that lets any LLM client **slice, paint and check
3D prints through the Bambu Studio command line** — for every Bambu printer and nozzle installed on
your machine, with your own filament presets, and with settings chosen per **type of object**.

> **Unofficial.** Not affiliated with, endorsed by or supported by Bambu Lab. "Bambu Lab" and
> "Bambu Studio" are trademarks of their owners.
>
> **It never prints.** No tool sends anything to a printer, over LAN or cloud, and nothing is ever
> opened in your Bambu Studio window. The server runs the headless slicer and writes files; you
> open the result in Bambu Studio and press print yourself.

[Leia em português](README.pt-BR.md)

## What it does

| Tool | |
|---|---|
| `list_printers` | Every installed printer + nozzle: bed, height, forbidden zones, defaults |
| `list_presets` | Process and filament presets compatible with a printer — yours included |
| `get_settings` | Every valid setting key with its value, and which ones can be set per object |
| `list_object_types` | functional, decorative, miniature, flat, enclosure, vase, draft, print_in_place |
| `analyze_model` | Size, fit, overhangs, bed contact, flat tops, suggested object type — **plus a preview image** |
| `slice_model` | Meshes → Bambu project → sliced and **verified**: time, grams per filament, purge, colour changes |
| `compare_slices` | The same model sliced several ways (process, `support_type`, `wall_loops`…) side by side |
| `slice_project` | Re-slice an existing `.3mf` (e.g. from MakerWorld) with other settings, filaments or printer |
| `paint_model` | Colour a single mesh by rules — height, facing, image projection, bucket fill — with preview |
| `self_test` | Proves the colour-paint encoding on your machine (run after updating Bambu Studio) |

Per-object and per-part settings, modifier volumes (a region with its own settings), negative
volumes and support blockers/enforcers are all supported.

### Why "verified"

Bambu Studio's CLI answers `Success.` for prints that are wrong. While building this, it did so for:
colour parts that dropped onto the bed as loose objects, a weight of 0 g, and a prime tower inside
the printer's forbidden zone. Every slice here is checked against what the project was meant to be,
and the result carries a `problems` list. **A non-empty list means the print is not ready.**

## Requirements

* **Bambu Studio** installed and opened at least once (it installs the printer profiles).
  Tested with 02.08.02.61.
* Python 3.10+.

## Install

```bash
pip install git+https://github.com/welingtonmatos/bambu-studio-mcp
```

or without installing anything permanently, with [uv](https://docs.astral.sh/uv/):

```bash
uvx --from git+https://github.com/welingtonmatos/bambu-studio-mcp bambu-studio-mcp
```

### Connect it to your client

**Claude Code**

```bash
claude mcp add bambu-studio -- bambu-studio-mcp
```

**Claude Desktop** (`claude_desktop_config.json`) and most other clients:

```json
{
  "mcpServers": {
    "bambu-studio": { "command": "bambu-studio-mcp" }
  }
}
```

If the client cannot find the command, use the full path of the `bambu-studio-mcp` executable
inside your Python environment.

**Non-default locations** — set these environment variables:

| Variable | Default |
|---|---|
| `BAMBU_STUDIO_EXE` | Windows `C:\Program Files\Bambu Studio\bambu-studio.exe` · macOS `/Applications/BambuStudio.app/Contents/MacOS/BambuStudio` · Linux `bambu-studio` on `PATH` |
| `BAMBU_STUDIO_CONFIG_DIR` | Windows `%APPDATA%\BambuStudio` · macOS `~/Library/Application Support/BambuStudio` · Linux `~/.config/BambuStudio` |
| `BAMBU_STUDIO_MCP_CACHE` | per-user cache folder |

## Using it

Ask in plain language — the model picks the tools:

> *"Slice `bracket.stl` for my P1S as a functional part in PETG and tell me how long it takes."*
>
> *"I have `keychain-black.stl` and `keychain-gold.stl` for the A1 mini. How much of the filament is purge?
> Would 3 per plate be faster per unit?"*
>
> *"Paint everything above 3.3 mm of `sign.stl` gold and the rest black, then show me the preview."*
>
> *"Compare tree and normal supports for `statue.stl`."*

Colour words in file or mesh names choose filament slots automatically (`-black`, `-gold`, `-red`,
and the Portuguese `-preto`, `-dourado`, `-vermelho`, …); a part without one is the base colour.

### Paint rules

```json
[
  {"type": "height",  "from": 3.3, "to": 99,                   "filament": 2},
  {"type": "facing",  "direction": "up", "angle": 20,          "filament": 2},
  {"type": "image",   "file": "logo.png", "view": "top",
                      "colors": {"#FF0000": 3, "#FFFFFF": 4},  "tolerance": 80},
  {"type": "body",    "index": 1,                              "filament": 3},
  {"type": "fill",    "point": [12.0, 4.5, 3.8], "angle": 30,  "filament": 4}
]
```

Rules apply in order. Any rule accepts `"within": [x0,y0,z0,x1,y1,z1]` and `"only_from": slot`.
Image projection paints side walls with the colour of their inside, so raised letters come out whole.

## How it works

* **Configuration for any printer.** There is no public schema for a project's settings, so the
  server asks Bambu Studio to write it: it slices a 20 mm cube with the printer's default process
  and filament, once with 1 filament and once with 2, and keeps what Bambu Studio saved. Comparing
  the two shows how every setting grows per filament. Cached per printer; refreshed when Bambu
  Studio updates. Presets are read from your installation and never bundled.
* **Object types** start from Bambu's own profiles — `functional` applies exactly what Bambu's
  "0.20mm Strength" changes — and pick the installed process whose layer height suits the nozzle.
  Every value used was sliced and confirmed to be kept by Bambu Studio and to have an effect.
* **Automatic adjustments** add tree supports (overhangs ≥ 3 % of the surface, ignoring hidden
  interfaces between parts) and an 8 mm brim (tall/narrow or little bed contact), per object.
  Anything you set explicitly wins. Turn off with `auto_adjust: false`.
* **Colour changes** are counted from the G-code; the number in Bambu's `result.json` is wrong.
* **Paint** is written per triangle in the same attribute the GUI brush uses; boundaries are made
  crisp by subdividing triangles to the requested resolution (mesh stays watertight).

## Tested

| | |
|---|---|
| OS | Windows 11 |
| Bambu Studio | 02.08.02.61 (profiles BBL 02.08.00.06) |
| Sliced end to end | A1 mini (0.4), P1S (0.4) |
| Listed, not sliced | the other 54 installed printer/nozzle presets |

macOS and Linux paths follow Bambu Studio's documented locations but are **untested** — reports and
pull requests are welcome. Dual-nozzle printers (H2D/H2C) are listed but not yet verified.

## Limitations

* Purge volumes use Bambu Studio's uncalibrated default (280 mm³ between any two filaments). Open
  the project in Bambu Studio and sync the AMS to recalculate them for your exact colours.
* One plate per project; height-range modifiers are not supported yet.
* Paint is per whole triangle (after subdivision); very fine artwork needs a small `resolution`,
  which makes larger files.

## Development

```bash
git clone https://github.com/welingtonmatos/bambu-studio-mcp && cd bambu-studio-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev]"     # Windows: .venv\Scripts\pip
pytest            # tests marked 'studio' are skipped when Bambu Studio is not installed
```

## License

MIT — see [LICENSE](LICENSE). This package contains no Bambu Studio code or profiles; it runs the
Bambu Studio executable you installed and reads the profiles on your machine.