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.
- 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, abambu://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.
- Python 3.12+
- LAN access to your printers
git clone https://github.com/synman/bambu-mcp.git
cd bambu-mcp
python3 make.pymake.py creates .venv/ inside the project and installs the package with all dependencies.
Run it again after any upstream dependency change.
- Discover: call
discover_printers()to find printers on your network by SSDP. - Get access code: on the printer touchscreen, Settings, Network, Access Code.
- Add: call
add_printer(...)with the name, IP, serial and access code, anduser_permission=True. - Verify: call
get_printer_state(name="myprinter").
Merge the "bambu-mcp" entry from config/claude_desktop.example.json into
~/Library/Application Support/Claude/claude_desktop_config.json, replacing <install-dir>.
Merge config/copilot_mcp.example.json into your Copilot MCP configuration.
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.
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 |
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
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.
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.
- Published docs: https://synman.github.io/bambu-printer-manager/bambu-mcp/. The pages are
generated by
gen_docs.pyfrom the tool docstrings,api_server.pyanddocs/site/overview.md. After changing any of those, run.venv/bin/python3 gen_docs.pyand 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.