Bambu Studio Headless MCP

English | 简体中文

An unofficial Model Context Protocol (MCP) server for Bambu Lab (拓竹) Bambu Studio on Windows. AI agents can prepare and inspect STL/3MF files and run offline slicing on an isolated desktop, while the mouse, keyboard and visible desktop remain available for other work. Includes an X2D dual-nozzle workflow validated against the 0.4/0.4 mm software baseline.

This independent project connects two useful building blocks: bambu-printer-mcp for MCP tools and slicing, and optional bambu-studio-ai skills for model preparation. It adds an isolated Windows launcher and an offline X2D dual-nozzle workflow. Bambu Studio must be installed separately.

What it does

• Runs each Bambu Studio CLI process on a separate, never-shown Windows desktop. CLI error dialogs remain there too; the launcher does not switch desktops or send mouse or keyboard input.

• Exposes a pinned bambu-printer-mcp 1.1.27 runtime through an MCP stdio bridge restricted to model preparation, inspection and slicing, with local configuration kept outside version control.

• Prepares two closed STL parts as one X2D dual-nozzle project, preserving their shared coordinates by default. The current builder supports the 0.4/0.4 mm software baseline. Independent objects can use a separate layout.

• Checks the sliced 3MF archive, X2D metadata, physical nozzle assignments and G-code tool use offline.

• Provides an optional, narrowly scoped X2D inspector compatibility adaptation for Bambu Studio 02.08.02.61 output. Its source and version guards must pass; it does not raise temperature limits or accept arbitrary G-code.

• Documents how to use bambu-studio-ai for modelling, mesh checks and previews, then hand slicing to this background bridge.

Related MCP server: OpenSCAD Design MCP

Requirements

• Windows with an interactive, unlocked desktop session. A hidden desktop is isolation inside that session, not a Windows service or a promise that GPU slicing works over every remote or locked session.

• Node.js 24 or later, Python 3.10 or later, and the C# build tools used by windows/build.ps1.

• A separately installed Bambu Studio with its own X2D machine/process/filament profiles when using the X2D workflow.

• Two closed STL meshes, a suitable X2D dual-nozzle template, and local filament profiles for a dual-nozzle job. Confirm the actual nozzle sizes and materials before preparing a file for physical printing.

Package installation may need internet access. Model preparation and slicing can run offline; no printer IP, serial number, access code or cloud account is needed.

Quick start

Clone this repository, open PowerShell in its root, and install the pinned dependency:

npm install
powershell -ExecutionPolicy Bypass -File windows/build.ps1
node scripts/setup.mjs --studio-exe '<installed Bambu Studio executable>'

Replace every <placeholder> before running a command. Setup saves local configuration in the ignored config/local.json and creates artifacts/codex-mcp.example.toml; it does not edit an MCP client's existing configuration. It does not bundle or upload Bambu Studio or its profiles. The compiled launcher is build/BambuCliHidden.exe. It uses BAMBU_STUDIO_EXE to locate the real executable, and the bridge sets that value from local configuration.

To opt into the guarded X2D inspector compatibility adaptation, add --enable-x2d-compat to the setup command. It is disabled by default. Read the compatibility boundaries before enabling it.

Start the MCP server with:

node scripts/server.mjs

For an MCP client, use the following generic configuration and replace the repository placeholder with the absolute path on that computer:

{
  "mcpServers": {
    "bambu_studio_headless_mcp": {
      "command": "node",
      "args": ["<absolute repository path>/scripts/server.mjs"]
    }
  }
}

The server uses stdio for MCP. Launch it through the MCP client rather than expecting a web page. A local one-shot client is also provided:

node scripts/call-tool.mjs <tool-name> <request.json>
node scripts/call-tool.mjs --list

Inspect the tool schema supplied by the running server before creating requests. The bridge rejects device credentials, executable overrides, non-Studio slicers and live-printer filament resolution; slicing always uses local profiles. Refer to architecture and runtime boundaries for the launcher, tool exposure and X2D compatibility details.

X2D dual-nozzle workflow

Use a genuine X2D project template prepared with the installed Bambu Studio profiles. Retain its inherited and included start/end/filament-change G-code; do not substitute an A1 or H2D template. The current builder accepts a single plate, two 0.4 mm nozzles, two filament slots and an explicit manual mapping to the two physical nozzles. It inherits project settings, then regenerates part metadata; source mesh painting and object-specific overrides are not reused.

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r python/requirements.txt
.venv\Scripts\python.exe examples/make_sample_parts.py --output-dir artifacts/demo
.venv\Scripts\python.exe python/prepare_dual_parts.py --template '<X2D project.3mf>' --part1 artifacts/demo/part_1.stl --part2 artifacts/demo/part_2.stl --output artifacts/dual.3mf --filament1 '<PLA.json>' --filament2 '<PLA.json>'
node scripts/call-tool.mjs slice_stl artifacts/dual.mcp.json
.venv\Scripts\python.exe python/verify_dual.py '<sliced output.3mf>'

The sample generator creates two original 8 mm cubes with a 4 mm gap. Replace them with your own STL files for real work. The preparation script writes a new project, a .mcp.json request sidecar and a .receipt.json preparation receipt; it refuses to overwrite existing output. Slice that request, then use the actual output path returned by the tool for verification. The default layout preserves assembly relationships; use --layout separate only for deliberately independent objects.

Both filament slots and physical nozzle mappings must be explicit. AMS spool slots are a separate choice. Two colours in a preview do not prove that two physical nozzles are used. The verifier uses filament_maps to connect material slots to physical nozzles; T and H values are not treated as physical nozzle IDs on their own. See the full X2D preparation and acceptance workflow.

Optional modelling Skill

bambu-studio-ai can supply parametric models, mesh analysis and previews. Its upstream GUI helpers and A1-based colour templates are not a background X2D workflow by themselves. Use the generic Skill integration guide to keep all Bambu CLI execution behind the hidden launcher and route dual-nozzle jobs through the X2D preparation path. The generic agent instructions in skills/bambu-studio-headless-mcp/SKILL.md can be read or copied into a supported Skill location. The upstream Skill is not bundled or automatically installed.

Limits and verification

• This is an unofficial bridge. It is not a complete background API for the Bambu Studio GUI: interactive painting and every GUI-only operation are outside its scope.

• It does not expose printer control or migrate device credentials. Device connection and printer actions are outside this bridge's offline setup and require separate tooling, configuration and an explicit operator request.

• The upstream native X2D printing helper currently supports macOS. This project does not turn it into a Windows printing helper or launch Bambu Connect as a fallback.

• Software checks establish file preparation and static inspection. They do not establish live printer connectivity, loaded spool identity, nozzle dimensions or successful physical printing.

• The hidden desktop avoids desktop takeover. It still uses CPU, memory and graphics resources; performance depends on the computer and installed Studio.

• The compatibility adaptation targets the pinned MCP version and identified Studio output. Unexpected versions, source hashes or G-code must fail closed. Re-run local acceptance after dependency or Studio upgrades.

Run the included software checks from the repository root:

npm test
.venv\Scripts\python.exe -m unittest discover -s tests -p 'test_dual*.py'
powershell -ExecutionPolicy Bypass -File windows/test-launcher.ps1

These checks are followed by a local slice of a known project when accepting a new Studio installation. None starts a print.

Privacy and provenance

This repository contains source code and generic examples. It does not bundle Bambu Studio, official system profiles, printer credentials, local account configuration or machine-specific logs. Keep generated files in artifacts/ and local configuration in config/; review any file before sharing it.

Thanks to the upstream authors of bambu-printer-mcp, bambu-studio-ai, and Bambu Studio. Their own licenses and terms apply to their software. This project does not claim affiliation with or endorsement by Bambu Lab or those upstream authors.

This repository's code is licensed under GPL-2.0-only.