Field notes and reference code for driving a Bambu Lab X2D from an LLM agent over the LAN protocol (MQTT + FTPS + RTSPS).
This is not another MCP server, and not another protocol dump. The LAN
protocol is already well covered by other projects — see Prior art
for a capability matrix of eight of them. Everything in this repo is what was
still missing after checking those eight, verified against a real X2D
(serial prefix 20P, firmware as of 2026-08).
1. Traditional Chinese HMS error text — docs/hms-zh-tw.md
Bambu's HMS error codes have official Traditional Chinese descriptions, but no
open-source project ships them. ha-bambulab — the only project with a
multi-language HMS text library — has 24 locale files, of which the only Chinese
ones are hms_zh-Hans and hms_zh_cn, both Simplified. bambuddy's
zh-TW.ts has zero HMS codes in it.
The tables exist on every machine that has Bambu Studio installed. This document
explains where they live, how the per-model filename maps to your printer's
serial number, and the JSON structure. Reference reader in
src/hms_text.py.
We do not redistribute the tables. They are Bambu's copyrighted resource files. This repo tells you how to read the copy you already have, which also means your text stays in sync when Studio updates.
2. Toolpath parsing as a structured query surface — docs/toolpath-llm.md
Of the eight projects surveyed, exactly one (bambuddy) parses G-code toolpaths
at all, and it renders them in a web UI. No project exposes toolpath geometry
as something an agent can ask questions about — "which layer is the colour
change on", "how much filament does this region use", "where is the print head
right now relative to the model".
3. Agent-facing control design — docs/x2d-protocol.md
All five existing Bambu MCP servers have zero occurrences of X2D. The
protocol notes here cover the X2D-specific fields, cross-referenced against
where each one is already implemented elsewhere, plus the parts that matter
specifically when a language model — rather than a human clicking a button — is
the one issuing commands.
Stated plainly, because it took a survey to find out:
| Thing | Already done by |
|---|---|
device.ctc.info.temp chamber temperature, packed low/high word |
ha-bambulab pybambu/models.py |
vir_slot external spool slots |
OrcaSlicer, BambuStudio, ha-bambulab, bambuddy, SpoolEase |
Dual-nozzle extruder.info[], packed temperatures |
ha-bambulab |
| HMS severity extraction from the code | ha-bambulab get_HMS_severity() |
| X2D model identification, certificates, RTSPS camera | bambuddy, ha-bambulab |
| LAN MQTT control, FTPS, print submission, AMS | all eight projects |
If you need those, use those projects. They are better maintained than this will be.
The printer must be in LAN Only Mode with Developer Mode enabled. Without
it, current firmware requires RSA-SHA256 command signing and rejects everything
except the chamber light. This is Bambu's authorization control system, not a
transport-layer issue — see docs/x2d-protocol.md.
Turning it on disconnects Bambu Cloud, the Handy app, and MakerWorld sync. It is reversible.
MIT — see LICENSE.
The HMS resource files this code reads are not covered by that license; they belong to Bambu Lab and are not included here.
這是把 Bambu Lab X2D 接給 LLM agent 用的實測筆記與參考程式碼。
不是又一個 MCP server,也不是又一份協定文件。 LAN 協定已經被其他專案寫得 很完整了(能力矩陣比對了八個)。這裡放的是把那八個查完 之後還空著的部分,全部對著一台真的 X2D 驗過。
三塊:
- HMS 錯誤碼繁體中文 — 官方有繁中說明,但沒有任何
開源專案帶。
ha-bambulab的 24 個語系檔裡中文只有簡體兩份。這份文件說明 官方表在哪、檔名的機型碼怎麼從序號推、JSON 長什麼樣。不轉載表本身, 那是 Bambu 的資源檔;讀你自己機器上那份,Studio 更新時還會跟著更新。 - 刀路解析成可查詢的結構 — 八個專案裡只有一個 會解 G-code 刀路,而且是畫成網頁。沒有人把刀路做成 agent 問得動的東西。
- 給 agent 用的控制設計 — 五個 Bambu MCP server
的
X2D命中數全部是 0。
這裡沒有的東西(ctc 腔溫、vir_slot、雙噴頭、HMS 嚴重度、X2D 機型識別
與憑證)上面表格標了各自已經做好的專案,需要就去用那些,它們維護得比這裡好。
印表機要開 LAN Only + Developer Mode,否則現在的韌體會要求 RSA-SHA256 指令簽章,除了腔燈以外全部拒絕。開了會斷雲端、Handy 與 MakerWorld,可以復原。