Bambu Lab Printer (LAN)

mcp-server-for-bambu

Claude（または Cursor、VS Code）に Bambu Lab プリンターの動作状況を尋ねたり、LAN 経由で一時停止、予熱、メンテナンスの記録を行ったりできます。クラウドは不要です。

Bambu Lab 3D プリンター用の MCP サーバーです。プリンターのローカル MQTT インターフェースを介して直接通信します。P1S で構築・テストしています。他の MQTT 対応モデル（P1P、X1C、A1）でも動作するはずです。

⚠️ 非公式 — Bambu Lab とは無関係です

これはコミュニティが開発したプロジェクトです。Bambu Lab / Shenzhen Tuozhu Technology Co., Ltd. とは提携、承認、またはスポンサー関係にありません。「Bambu Lab」、「Bambu Studio」、「P1S」、「P1P」、「X1C」、「AMS」はそれぞれの所有者の商標です。本プロジェクトでの言及は、互換性を目的とした説明的なもの（指名的フェアユース）に限られます。保証なしの「現状有姿」で提供されます。

デモ

内蔵プリンターシミュレーター（npm run sim）を使った実際のツール呼び出しと出力です。scripts/demo/ で再生成できます。実機プリンターでセッションを記録する方法については、docs/demo-script.md をご覧ください。

機能

リアルタイムの状態	状態、現在の工程、進捗、レイヤー、残り時間、ノズル／ベッド／チャンバーの温度、Wi-Fi 信号
AMS	スロットごとのフィラメントの種類、ブランド、色、残量（%）、およびアクティブなスロット
ヘルス状態	アクティブな HMS 警告をモジュールと重大度に分類し、それぞれに Bambu wiki へのリンクを表示
制御	一時停止、再開、キャンセル、チャンバーライト、速度プロファイル、予熱、AMS スロット切り替え、生の G-code
メンテナンス記録	印刷時間をローカルでカウントし、レール、カーボンロッド、ホットエンドの交換時期を通知
ガイド付きセットアップ	設定ファイルの編集は不要です。Claude に IP、シリアル番号、アクセスコードを伝えると、保存前にテストします
安全性	キャンセル、G-code、AMS の切り替えには明示的な確認が必要です。読み取り専用モード、LAN アドレスのみ
MCP 対応環境ならどこでも動作	Claude Code プラグイン、Claude Desktop、Cursor、VS Code、stdio MCP クライアント全般
プリンターシミュレーター	npm run sim で、試用、デモ、テスト用の疑似プリンターを起動します

クイックスタート

Node.js 20 以降と、LAN Mode Liveview を有効にした同一ネットワーク上のプリンターが必要です。

Claude Code

プラグインをインストールします（MCP サーバーと、確認ルールを Claude に教える短いスキルが含まれます）。

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

または、MCP サーバーのみを追加します。

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

Claude Desktop

Settings → Developer → Edit Config を開き（Windows では %APPDATA%\Claude\claude_desktop_config.json、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）、次の内容を追加します。

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

Claude Desktop を完全に終了し（トレイアイコン → Quit）、再起動します。

Cursor

または、~/.cursor/mcp.json（すべてのプロジェクト）か .cursor/mcp.json（単一のプロジェクト）に次の内容を記述します。

{
  "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\"]}"

または、.vscode/mcp.json に追加します。このバージョンでは認証情報を環境変数として渡し、非表示の入力欄でアクセスコードを尋ねます。

{
  "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}"
      }
    }
  }
}

これらの設定例はすべて examples/ にあります。

プリンターを接続する

初回起動時、サーバーはセットアップモードになり、setup_printer というツールを1つ提供します。プリンターのタッチスクリーンで次の3つの値を確認します。

• IP：Settings → WLAN → 接続中のネットワークをタップします
• シリアル番号：Settings → Device → Device Info（P1S：01P00A…）
• アクセスコード：Settings → WLAN → LAN Mode Liveview の8文字のコードです。Wi-Fiパスワードではありません。LAN Mode Liveviewをオンにしてください。

次のようにアシスタントに伝えます。

「Bambuプリンターをセットアップしてください。IPは192.168.1.50、シリアル番号は01P00A1234567890、アクセスコードは12345678です。」

setup_printer は形式を確認してプリンターに接続し、接続に成功した場合にのみ認証情報を保存します。サーバーを一度再起動すると（Claude Desktop：終了して再度開く、Claude Code：/mcp → bambu に再接続）、プリンターツールが表示されます。

この手順を省略し、VS Codeの例のように環境変数として BAMBU_IP、BAMBU_SERIAL、BAMBU_ACCESS_CODE を渡すこともできます。

試してみる

• 「今、プリンターはどんな状態ですか？」
• 「AMSのスロット2にはどのフィラメントが入っていますか？」
• 「HMSの警告はありますか？」
• 「プリンターのメンテナンスで期限を過ぎているものはありますか？」
• 「プリントを一時停止してください。」／「再開してください。」
• 「ノズルを210、ベッドを60に予熱してください。」
• 「このプリントをキャンセルしてください。」（先に確認を求めます）
• 「レールに注油しました。記録してください。」

ツール

ツール	機能	先に確認しますか？
get_status	状態、工程、温度、進捗、レイヤー、HMSの警告、Wi-Fi
get_ams_info	スロットごとのフィラメントの種類／色／残量％、アクティブなスロット
list_active_warnings	BambuのWikiへのリンク付きのアクティブなHMS警告
get_maintenance_status	プリント時間と、注油／清掃／点検の警告
forecast_maintenance	最近のプリント頻度に基づく、各メンテナンス作業の期限
get_recent_prints	直近N回のプリントセッション：名前、所要時間、終了時刻
mark_maintenance_done	メンテナンス作業を記録します（hours_ago で過去の日時を指定することもできます）
pause_print / resume_print	現在のプリントを一時停止／再開します
set_light	チャンバーライトをオン／オフにします
set_speed	サイレント／標準／スポーツ／ルディクラス
preheat	ノズルやベッドの目標温度を設定します
stop_print	プリントをキャンセルします。取り消しできません	はい（confirm: true）
run_gcode	G-codeを直接送信します（原点復帰、Z軸移動、手動アンロードなど）	はい（confirm: true）
change_active_tray	AMSを別のスロットに切り替えます	はい（confirm: true）

すべてのツールにはMCPアノテーション（readOnlyHint、destructiveHint）も付与されているため、ツールの実行前に確認するクライアントは、読み取り専用ツールと破壊的な操作を行うツールを区別できます。

安全性

このサーバーは、高温のツールヘッドを動かしたり、何時間ものプリントをキャンセルしたりできます。誤操作を起こしにくくするため、次の対策を講じています。

• 破壊的なツールには確認が必要です。 stop_print、run_gcode、change_active_tray は、confirm: true を指定しないと実行されません。また、説明では、あなたが明確な言葉で同意した後にのみ設定するようモデルに指示しています。二重の確認として、クライアント側のツール承認プロンプトも有効にしてください。
• 読み取り専用モード。 BAMBU_READ_ONLY=1 を設定すると、サーバーには読み取りツールのみが登録されます。プリンターの一時停止、キャンセル、加熱、移動はできません。共有マシンやデモに適したデフォルト設定です。
• LAN のみ。 設定したプリンター IP のポート 8883 にのみ接続し、それ以外には接続しません。Bambu のクラウドにもテレメトリーにも接続しません。setup_printer はプライベートアドレス範囲（192.168.x.x、10.x.x.x、172.16–31.x.x.x に加え、リンクローカル、ループバック、Tailscale が使用する 100.64/10 の範囲）以外のアドレスを拒否します。プリンターの MQTT ポートをインターネットに転送しないでください。
• 信頼できるネットワークを使用してください。 プリンターは自己署名証明書を使用するため、接続は暗号化されますが、プリンターの身元は検証されません。信頼できるネットワーク上で使用してください。
• ヒーターはオンのままです。 preheat および M104／M140 は、何かが変更するまでヒーターを目標温度に保ちます。その場を離れる前に、温度を 0 に設定してオフにしてください。
• 認証情報はローカルに保存されます。 ユーザー設定ディレクトリ（下記）に保存され、macOS と Linux では所有者のみがアクセスできる権限が設定されます。

設定

環境変数	デフォルト	意味
BAMBU_IP、BAMBU_SERIAL、BAMBU_ACCESS_CODE	保存済みの .env から取得	プリンターの認証情報。環境変数は保存済みファイルより優先されます
BAMBU_READ_ONLY	0	1 にすると、読み取りツールのみが登録されます
BAMBU_CONFIG_DIR	下記を参照	.env とメンテナンス記録の保存場所
MAINTENANCE_LEDGER_PATH	<config dir>/maintenance.json	記録ファイルの保存場所

設定ディレクトリは次のとおりです。

• Windows：%APPDATA%\mcp-server-for-bambu\
• macOS：~/Library/Application Support/mcp-server-for-bambu/
• Linux：~/.config/mcp-server-for-bambu/（または $XDG_CONFIG_HOME）

0.2.0 以前のバージョンでは、.env と maintenance.json はインストール済みパッケージ内に保存されていたため、npx の更新時に削除されることがありました。0.3.0 では、以前の場所にある古い .env も読み込み、初回起動時に古い記録を設定ディレクトリへコピーします。

記録はローカルの JSON ファイルに保存され、クラッシュ後も保持されます（アクティブなセッションは、経過時間 5 分ごとにチェックポイントが保存されます）。しきい値は src/types.ts にあります。

タスク	間隔
カーボンロッドの清掃	100 プリント時間
リニアレールの潤滑	200 プリント時間
ホットエンド／ノズルの摩耗点検	500 プリント時間

しきい値まで 10 時間以内になるとタスクは DUE_SOON（🔔）に変わり、しきい値を過ぎると OVERDUE（⚠️）になります。

プリンターなしで試す

クローンしたリポジトリで npm install を実行した後、npm run sim を実行すると、4 スロットの AMS を備えた、プリント途中の P1S をシミュレートする環境が mqtts://127.0.0.1:8883 で起動します。ステータス要求に応答し、一時停止、再開、キャンセル、速度、予熱、ライト、AMS の各コマンドを適用します。サーバーの接続先を次のように設定してください。

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

別のポートを使用するには SIM_PORT を設定し、その値を BAMBU_MQTT_PORT にも渡してください。テストスイートでも同じシミュレーターを使用します。

開発

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

MCP クライアントからローカルビルドを実行するには、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

プロトコルに関する注意：

• 購読：device/{serial}/report
• 発行：{"pushing":{"sequence_id":"...","command":"pushall"}} を指定して device/{serial}/request に送信
• 認証：ユーザー名は bblp、パスワードはアクセスコード、接続ごとにランダムなクライアント ID を使用します（同じ ID を再利用すると、2 つのクライアントが互いの接続を切断します）
• 証明書は自己署名です → rejectUnauthorized: false

ライセンス

MIT