bambu-mcp

bambu-mcp is a Model Context Protocol server that lets AI agents monitor and control Bambu Lab printers. It is built on bambu-printer-manager and keeps one live MQTT session per configured printer. The same process also serves a REST API and MJPEG camera streams.

Source: synman/bambu-mcp on GitHub.

At a glance

Surface	Count	Reference
MCP tools	104 (51 read-only, 53 write, 50 need `user_permission=True`)	MCP Tools
REST API routes	87	REST API
MCP resources	4 rules files plus 1 alert feed template	Resources
MCP prompts	1 (`bambu_system_context`)	Resources

Requirements

Python 3.12 or newer.
Each printer powered on and on the same local network as the server.
Each printer's IP address, serial number and access code. The access code is on the printer's touchscreen under Settings, Network.

Installation

Bash

git clone https://github.com/synman/bambu-mcp.git
cd bambu-mcp
python3 make.py

Run make.py with Python 3.12 or newer, for example python3.12 make.py: the virtual environment uses the interpreter that runs it. make.py creates a .venv inside the project and installs bambu-mcp with its dependencies, including bambu-printer-manager from its devel branch. Run it again to pick up dependency updates.

Running the server

Transport	Command	Listens on
stdio (default)	`.venv/bin/python3 server.py`	the client's stdin and stdout
Streamable HTTP	`.venv/bin/python3 server.py --transport streamable-http`	`http://127.0.0.1:25099/mcp`
SSE	`.venv/bin/python3 server.py --transport sse`	`http://127.0.0.1:8000/sse`

In Streamable HTTP mode only one server runs per machine. If port 25099 is taken it scans down to 25000 and writes the port it chose to ~/.bambu-mcp/daemon.port. Every transport connects to the configured printers in the background, so tools answer at once and printer data arrives as each session connects. When at least one printer is configured at startup, the server also starts the REST API.

Client configuration

A stdio client starts the server itself and talks to it over stdin and stdout. Point it at the project's Python and server.py. The repo ships config/claude_desktop.example.json for Claude Desktop:

JSON

{
  "mcpServers": {
    "bambu-mcp": {
      "command": "<install-dir>/bambu-mcp/.venv/bin/python3",
      "args": ["<install-dir>/bambu-mcp/server.py"],
      "env": {
        "PYTHONPATH": "<install-dir>/bambu-mcp"
      }
    }
  }
}

config/copilot_mcp.example.json is the same entry for GitHub Copilot CLI. A client that speaks Streamable HTTP can connect to a running server at http://127.0.0.1:25099/mcp instead, using the port in ~/.bambu-mcp/daemon.port if it differs.

Adding a printer

Call discover_printers to find printers on the local network by SSDP.
Read the access code from the printer's touchscreen.
Call add_printer with the name, IP address, serial number and access code, and user_permission=True.
Call get_printer_state with the new name to confirm the session is live.

Printer credentials are stored encrypted with AES-256-GCM. The master key comes from the BAMBU_MCP_SECRETS_KEY environment variable, else the OS keychain, else a local key file.

Safety model

Write guard. Every tool that changes printer or server state refuses unless called with user_permission=True. Without it the tool changes nothing and returns a refusal that names the consequence. The MCP Tools page marks each one.
Active-print guard. Tools that would disturb a running print refuse while the printer is printing or preparing, even with user_permission=True.
Tool annotations. Every tool declares a title and read-only, destructive, idempotent and open-world hints, so a client can grant read-only tools on their own.

REST API

The REST API exposes the same printer sessions over HTTP. Its port comes from a shared pool starting at 49152, so it is not fixed. Find it with the get_server_info tool or GET /api/server_info. The running server also publishes a Swagger UI at /api/docs and the OpenAPI document at /api/openapi.json.

No authentication

The REST API and the camera streams listen on all network interfaces and ask for no credentials. Anyone who can reach the port can read printer state, and the REST API accepts commands. Run bambu-mcp only on a trusted network.

Full route list: REST API.

Camera streams

start_stream and view_stream start a local MJPEG server for a printer's camera, on a port from the same pool. The camera protocol follows the printer model:

Protocol	Models
RTSPS, port 322	X1C, X1, X1E, P2S, H2D, H2S
TLS, port 6000	A1, A1 Mini, P1P, P1S

get_snapshot returns a URL for one still frame without starting a stream.

Resources and prompt

URI or name	What it returns
`bambu://rules/global`	The server host's global agent rules file, with IPs, serials and credentials redacted
`bambu://rules/printer-app`	The bambu-printer-app agent rules file, redacted
`bambu://rules/printer-manager`	The bambu-printer-manager agent rules file, redacted
`bambu://rules/bambu-mcp`	The bambu-mcp agent rules file, redacted
`bambu://alerts/{name}`	Pending state-change alerts for one printer as JSON, without clearing them
`bambu_system_context` (prompt)	Safety rules and tool guidance to load at the start of a session

The rules resources read files from the server's home directory, so their content depends on the machine running the server.