Skip to content
synmanPublic

About

Bambu Lab MCP server — LAN-mode control over Bambu Lab 3D printers via MQTT and FTPS

Resources

Stars

6 stars

Watchers

0 watching

Forks

Latest commit

 

History

291 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bambu Lab MCP Server

Version: 1.1.0 · Follows Semantic Versioning

An MCP (Model Context Protocol) server that lets AI agents monitor and control Bambu Lab 3D printers. It is built on bambu-printer-manager and keeps one live MQTT session per printer. The same process serves a REST API and live camera streams. No Docker or container is needed.

Documentation: https://synman.github.io/bambu-printer-manager/bambu-mcp/, with the full MCP tool reference and REST API reference.


Features

  • MCP tools for discovery, state, print control, climate, filament and AMS, nozzles, detectors, files, camera, alerts and charts. Every tool carries a title and read-only, destructive, idempotent and open-world annotations.
  • Write protection: every state-changing tool refuses unless called with user_permission=True, and tools that would disturb a print refuse while the printer is printing.
  • A REST API over the same sessions, with a Swagger UI at /api/docs.
  • Live camera streams for every model through the bambu-mse-stream relay: RTSPS H.264 passed through for X1, P2S and H2 series, TLS port 6000 stills encoded once for A1 and P1, played in the browser as fragmented MP4 (Media Source Extensions).
  • Printer credentials encrypted at rest with AES-256-GCM, keychain-backed master key.
  • 4 bambu://rules/* resources, a bambu://alerts/{name} alert feed and one prompt, bambu_system_context.

Security: the REST API and camera streams listen on all network interfaces with no authentication. Run bambu-mcp only on a trusted network.


Installation

Prerequisites

  • Python 3.12+
  • LAN access to your printers

Setup

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

make.py creates .venv/ inside the project and installs the package with all dependencies. Run it again after any upstream dependency change.

Add your first printer

  1. Discover: call discover_printers() to find printers on your network by SSDP.
  2. Get access code: on the printer touchscreen, Settings, Network, Access Code.
  3. Add: call add_printer(...) with the name, IP, serial and access code, and user_permission=True.
  4. Verify: call get_printer_state(name="myprinter").

Client Configuration

Claude Desktop

Merge the "bambu-mcp" entry from config/claude_desktop.example.json into ~/Library/Application Support/Claude/claude_desktop_config.json, replacing <install-dir>.

GitHub Copilot CLI

Merge config/copilot_mcp.example.json into your Copilot MCP configuration.

Streamable HTTP

Run .venv/bin/python3 server.py --transport streamable-http and point the client at http://127.0.0.1:25099/mcp. Running it as a supervised daemon: docs/operators-guide.md.


Tools

104 tools (51 read-only, 53 write) and 87 REST routes. Full reference: bambu-mcp docs.

Category Tools
Printer State get_ams_status, get_capabilities, get_fan_speeds, get_hms_errors, get_job_info, get_print_progress, get_printer_info, get_printer_state, get_spool_info, get_temperatures, get_wifi_signal
Print Control clear_print_error, pause_print, resume_print, select_extrusion_calibration, send_gcode, set_print_option, set_print_speed, skip_objects, stop_print
Climate get_chamber_light, get_climate, set_bed_temp, set_chamber_light, set_chamber_temp, set_fan_speed, set_nozzle_temp
Filament & AMS calibrate_ams_remaining, get_ams_units, get_external_spool, get_filament_catalog, load_filament, send_ams_control_command, set_ams_filament_setting, set_ams_user_setting, start_ams_dryer, stop_ams_dryer, unload_filament
Nozzles get_nozzle_info, refresh_nozzles, set_nozzle_config, swap_tool
Detectors get_detector_settings, set_air_printing_detection, set_buildplate_marker_detection, set_first_layer_inspection, set_nozzle_clumping_detection, set_purge_chute_detection, set_spaghetti_detection
Printer Management add_printer, disconnect_printer, get_configured_printers, get_printer_connection_status, remove_printer, start_printer, update_printer_credentials
Files create_folder, delete_file, download_file, get_3mf_entry_by_id, get_3mf_entry_by_name, get_all_project_info, get_current_job_project_info, get_file_info, get_plate_thumbnail, get_plate_topview, get_project_info, list_sdcard_files, open_plate_layout, open_plate_viewer, preview_ams_mapping, print_file, refresh_sdcard, rename_sdcard_file, upload_file
System dump_log, force_state_refresh, get_firmware_version, get_server_info, get_session_status, get_user_pref, pause_mqtt_session, rename_printer, resume_mqtt_session, set_print_options, set_user_pref, trigger_printer_refresh, truncate_log
Discovery discover_printers
Raw Commands send_mqtt_command
Camera analyze_active_job, get_stream_url, open_job_state, start_stream, stop_stream, view_stream
Alerts get_pending_alerts
Snapshots & Monitoring Data get_monitoring_data, get_monitoring_history, get_monitoring_series, get_snapshot
Charts open_charts, render_charts_html, render_charts_panels

Architecture

bambu-mcp/
├── server.py            ← FastMCP entry point: tools, resources, prompt, startup
├── api_server.py        ← REST API and OpenAPI document
├── session_manager.py   ← Persistent BambuPrinter MQTT sessions
├── data_collector.py    ← Telemetry history per printer
├── notifications.py     ← State-change alert queue
├── secrets_store.py     ← AES-256-GCM secrets store
├── auth.py              ← Printer credential CRUD on top of secrets_store
├── job_project.py       ← Running job's resolved .3mf path per printer
├── port_pool.py         ← Shared port pool for the REST API and camera streams
├── daemon_port.py       ← Streamable HTTP port and singleton handling
├── gen_docs.py          ← Generates the published docs pages and the Tools section above
├── make.py              ← Cross-platform venv installer
├── camera/              ← camera relay, stream page, RTSPS and TCP-TLS clients, job monitor and analyzer
├── calibration/         ← Calibration scripts
├── tools/               ← Tool modules, plus _registry.py (registration and annotations)
├── resources/rules.py   ← bambu://rules/* readers (redacted)
├── prompts/context.py   ← bambu_system_context prompt
├── docs/                ← Operators guide, LAN file tunnel protocol, site overview source
└── config/              ← Example client configs and settings template

Versioning

The version of record is __version__ in server.py, plain semver with no suffix. pyproject.toml repeats it, and test_version.py fails when the two differ. The README header line carries a copy that python make.py version-sync refreshes. The MCP initialize response reports it as serverInfo.version. The REST OpenAPI info.version and the mDNS record read the same constant. Nothing derives it from package metadata.

Raise it by hand with every change to a serving file:

  • MAJOR: a tool removed or renamed, or a parameter or return shape changed incompatibly.
  • MINOR: a tool or behaviour added.
  • PATCH: a fix, hardening, or a wording change to a tool description, docstring or the server instructions.

Tests, docs, config, calibration/ and the standalone scripts (make.py, gen_docs.py, smoke_test.py, thermal_snapshot_monitor.py) need no bump. SERVING in hooks/version_bump_gate.py lists the files that do: the top-level modules the daemon imports and every .py under tools/, camera/, prompts/ and resources/. A pre-commit gate blocks a commit that stages one while __version__ is unchanged against HEAD. Install it once per clone: python3 hooks/version_bump_gate.py --install. The steps to release a change, and to read the version back from the running daemon, are in docs/operators-guide.md — Release a change.


Dependencies

bambu-mcp consumes the libraries below and names them here so the set is known. It carries nothing about the programs that consume it.

Declared in pyproject.toml:

Package Used for
bambu-printer-manager the printer sessions: MQTT, FTPS and state (the one Bambu-specific dependency)
mcp the MCP server and its streamable-http transport
flask, flask-cors the REST API
av, pillow, numpy camera frames, stills and the job-health image analysis
cryptography, keyring the encrypted printer-credential file and its master key
zeroconf the mDNS record that advertises the API
setproctitle the process title

Used through a declared package, so not declared again: pydantic and starlette (through mcp, for alert models and the HTTP app in tests) and webcolors (through bambu-printer-manager, for filament colour names).

Standalone scripts only, not installed with the server: matplotlib and scipy (thermal_snapshot_monitor.py and the plot scripts in docs/).

Known gap: camera/coord_transform.py imports matplotlib.path inside a function, and matplotlib is not declared. Declaring it is a dependency change and waits for the owner.

test_dependencies.py enforces this section. A third-party import in a tracked Python file that is not declared, listed above or in that test fails it, and so does a declared package that nothing imports.


Documentation

  • Published docs: https://synman.github.io/bambu-printer-manager/bambu-mcp/. The pages are generated by gen_docs.py from the tool docstrings, api_server.py and docs/site/overview.md. After changing any of those, run .venv/bin/python3 gen_docs.py and commit the regenerated pages in bambu-printer-manager.
  • docs/operators-guide.md: daemon administration, restarts, logging and ports.
  • docs/lan-file-tunnel-protocol.md: the port 6000 LAN file tunnel on H2-series, P2S and X2D.

About

Bambu Lab MCP server — LAN-mode control over Bambu Lab 3D printers via MQTT and FTPS

Resources

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages