mcp-server-for-bambu

Ask Claude (or Cursor, or VS Code) what your Bambu Lab printer is doing, and have it pause, preheat or log maintenance, over your LAN with no cloud.

An MCP server for Bambu Lab 3D printers. It talks to the printer directly over its local MQTT interface. Built and tested against the P1S; other MQTT-speaking models (P1P, X1C, A1) should work.

⚠️ Unofficial — not affiliated with Bambu Lab

This is a community-built project. It is not affiliated with, endorsed by, or sponsored by Bambu Lab / Shenzhen Tuozhu Technology Co., Ltd. "Bambu Lab", "Bambu Studio", "P1S", "P1P", "X1C", and "AMS" are trademarks of their respective owners; references in this project are descriptive only (nominative fair use), made for compatibility purposes. Provided "as is" with no warranty.

Demo

Real tool calls and output, run against the built-in printer simulator (npm run sim). Regenerate with scripts/demo/; docs/demo-script.md covers recording a session with a real printer.

Related MCP server: Bambuddy MCP Server

Features

Quick start

You need Node.js 20+ and a printer on the same network with LAN Mode Liveview turned on.

Claude Code

Install the plugin (MCP server plus a short skill that teaches Claude the confirmation rules):

/plugin marketplace add b84330808/mcp-server-for-bambu
/plugin install bambu-printer@mcp-server-for-bambu

Or add just the MCP server:

claude mcp add --transport stdio --scope user bambu -- npx -y mcp-server-for-bambu

Claude Desktop

Open Settings → Developer → Edit Config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:

{
  "mcpServers": {
    "bambu": {
      "command": "npx",
      "args": ["-y", "mcp-server-for-bambu"]
    }
  }
}

Fully quit Claude Desktop (tray icon → Quit) and reopen it.

Cursor

Or put this in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "bambu": {
      "command": "npx",
      "args": ["-y", "mcp-server-for-bambu"]
    }
  }
}

VS Code

code --add-mcp "{\"name\":\"bambu\",\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"mcp-server-for-bambu\"]}"

Or add it to .vscode/mcp.json. This version passes the credentials as env vars and asks for the access code as a hidden input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bambu-access-code",
      "description": "Bambu LAN access code (Settings > WLAN > LAN Mode Liveview)",
      "password": true
    }
  ],
  "servers": {
    "bambu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-for-bambu"],
      "env": {
        "BAMBU_IP": "192.168.1.50",
        "BAMBU_SERIAL": "01P00A1234567890",
        "BAMBU_ACCESS_CODE": "${input:bambu-access-code}"
      }
    }
  }
}

All of these are in examples/.

Connect your printer

On first start the server is in setup mode and offers one tool, setup_printer. Read three values off the printer's touchscreen:

• IP: Settings → WLAN → tap the connected network

• Serial: Settings → Device → Device Info (P1S: 01P00A…)

• Access code: Settings → WLAN → LAN Mode Liveview, 8 characters, not the Wi-Fi password. LAN Mode Liveview must be ON.

Then tell your assistant:

"Set up my Bambu printer. IP is 192.168.1.50, serial 01P00A1234567890, access code 12345678."

setup_printer checks the format, connects to the printer, and saves the credentials only if the connection works. Restart the server once (Claude Desktop: quit and reopen; Claude Code: /mcp → reconnect bambu) and the printer tools appear.

You can skip this and pass BAMBU_IP, BAMBU_SERIAL and BAMBU_ACCESS_CODE as env vars instead, as in the VS Code example.

Try it

• "What's my printer doing right now?"

• "What filament is in AMS slot 2?"

• "Any HMS warnings?"

• "Anything overdue on the printer maintenance?"

• "Pause the print." / "Resume."

• "Preheat the nozzle to 210 and bed to 60."

• "Cancel this print." (asks you to confirm first)

• "I just lubricated the rails, log it."

Tools

Every tool also carries MCP annotations (readOnlyHint, destructiveHint), so clients that ask before running tools can treat the read tools and the destructive ones differently.

Safety

This server can move a heated toolhead and cancel hours of printing. It is built to make that hard to do by accident:

• Confirmation for destructive tools. stop_print, run_gcode and change_active_tray refuse to run unless called with confirm: true, and their descriptions tell the model to set it only after you agree in plain words. Keep your client's own tool-approval prompts on as a second check.

• Read-only mode. Set BAMBU_READ_ONLY=1 and the server registers only the read tools. Nothing can pause, cancel, heat or move the printer. A good default for a shared machine or a demo.

• LAN only. It connects to the one printer IP you configure, on port 8883, and nowhere else: no Bambu cloud, no telemetry. setup_printer rejects addresses outside private ranges (192.168.x.x, 10.x.x.x, 172.16–31.x.x, plus link-local, loopback and the 100.64/10 range Tailscale uses). Never forward the printer's MQTT port to the internet.

• Trusted network. The printer uses a self-signed certificate, so the connection is encrypted but the printer's identity is not verified. Use it on a network you trust.

• Heaters stay on. preheat and M104/M140 leave the heaters at the target until something changes them. Turn them off (set 0) before you walk away.

• Credentials stay local. They are stored in your user config directory (below), with owner-only permissions on macOS and Linux.

Configuration

The config directory is:

• Windows: %APPDATA%\mcp-server-for-bambu\

• macOS: ~/Library/Application Support/mcp-server-for-bambu/

• Linux: ~/.config/mcp-server-for-bambu/ (or $XDG_CONFIG_HOME)

Versions up to 0.2.0 kept .env and maintenance.json inside the installed package, where npx updates could delete them. 0.3.0 still reads an old .env from there and copies an old ledger into the config directory on first start.

The ledger persists to a local JSON file and survives crashes (active sessions are checkpointed every 5 elapsed minutes). Thresholds are in src/types.ts:

A task flips to DUE_SOON (🔔) within 10 hours of the threshold and OVERDUE (⚠️) past it.

Try it without a printer

npm run sim (from a clone, after npm install) starts a simulated P1S halfway through a Benchy, with a 4-slot AMS, on mqtts://127.0.0.1:8883. It answers status requests and applies pause, resume, cancel, speed, preheat, light and AMS commands. Point the server at it:

BAMBU_IP=127.0.0.1 BAMBU_SERIAL=01P00ASIMULATOR BAMBU_ACCESS_CODE=12345678 node dist/index.js

Set SIM_PORT to use another port, then pass the same value as BAMBU_MQTT_PORT. The test suite uses the same simulator.

Development

git clone https://github.com/b84330808/mcp-server-for-bambu.git
cd mcp-server-for-bambu
npm install
npm test             # builds, then runs unit + end-to-end tests against the simulator
npm run dev          # tsc --watch
npm run sim          # simulated printer

To run your local build from an MCP client, point it at node /absolute/path/to/mcp-server-for-bambu/dist/index.js.

src/
  index.ts          MCP server bootstrap + tool definitions
  config.ts         Env / .env loading, LAN address check
  paths.ts          Per-user config directory
  mqtt-client.ts    TLS MQTT client for the printer (port 8883, self-signed cert)
  setup.ts          setup_printer: validate, test the connection, save
  maintenance.ts    Print-time ledger with crash-safe atomic writes + recovery
  hms.ts            Bambu HMS error code → human label
  stages.ts         Stage / speed / tray code → human label
  commands.ts       MQTT command payloads
sim/printer.mjs     Simulated printer (aedes broker over TLS)
plugins/            Claude Code plugin; .claude-plugin/marketplace.json lists it
server.json         MCP Registry metadata

Protocol notes:

• Subscribe: device/{serial}/report

• Publish: device/{serial}/request with {"pushing":{"sequence_id":"...","command":"pushall"}}

• Auth: username bblp, password = access code, a random client ID per connection (reusing one makes two clients kick each other off)

• Cert is self-signed → rejectUnauthorized: false

License

MIT