bambu-cloud-mcp

Bambu Lab 3D 프린터를 모든 MCP 클라이언트에서 제어하세요 — 클라우드를 통해 어디서나, LAN에서는 실시간 챔버 카메라 캡처까지.

MCP(Model Context Protocol) 서버로, AI 어시스턴트(Claude Code, Claude Desktop 또는 모든 MCP 클라이언트)가 Bambu Lab 프린터를 모니터링하고 제어할 수 있게 해줍니다. MQTT를 통해 LAN 또는 Bambu 클라우드 브로커(us.mqtt.bambulab.com / cn.mqtt.bambulab.com)로 프린터와 통신하므로, 프린터를 LAN-Only 모드로 전환하지 않아도 어디서나 상태 확인과 제어가 가능합니다. 상태, 인쇄 제어, 온도, AMS/필라멘트, 파일, 실시간 LAN 챔버 카메라 스냅샷을 다루는 31개 도구를 제공합니다.

다른 Bambu MCP 서버보다 이 서버가 나은 이유

대부분의 커뮤니티 Bambu MCP 서버는 LAN 제어만 지원하거나, 읽기 전용 클라우드 상태만 지원합니다. 이 서버는 보통 제공하지 않는 두 가지를 제공합니다:

• 완전한 클라우드 제어 — Bambu 클라우드 MQTT 브로커가 로컬 브로커와 동일한 명령 토픽(device/<serial>/request)을 수락하므로 모든 명령(일시 정지, 재개, 중지, 온도 설정, 필라멘트 교체, 원시 G-code 등)이 인터넷을 통해 작동합니다. 계정으로 한 번 로그인하면 연결된 프린터가 자동으로 연결됩니다.

• 실시간 챔버 카메라 — get_camera_frame이 LAN을 통해 A1 / A1 Mini / P1P / P1S 프린터에서 실제 JPEG 스냅샷을 가져와 MCP 클라이언트가 표시할 수 있는 이미지로 반환합니다.

카메라는 LAN 전용입니다. Bambu는 클라우드 영상 피드를 독점 P2P 시스템(TUTK)으로 터널링하며, 이는 오픈 소스로 재구현할 수 없습니다. 따라서 카메라는 기기가 프린터와 같은 네트워크에 있을 때만 작동합니다. 상태 확인과 제어는 어디서나 가능합니다.

Related MCP server: 3D Printer MCP Server

지원되는 프린터

• 제어(LAN + 클라우드): A1, A1 Mini, P1P, P1S, X1C, X1E, H2D 및 기타 최신 모델.

• 카메라(LAN 전용): A1, A1 Mini, P1P, P1S — 포트 6000 챔버 이미지 프로토콜 사용. X1/H2 시리즈는 대신 RTSP를 사용하며 아직 연결되지 않았습니다 — PR 환영합니다.

도구

영역별로 정리된 31개 도구:

클라우드

프린터 관리

상태

인쇄 제어

하드웨어

AMS / 필라멘트

G-code

파일 (LAN, FTPS)

카메라 (LAN 전용)

서명

요구 사항

• Node.js 18+

• 클라우드 제어용: Bambu Lab 계정(프린터가 연결된 계정). 개발자 토큰은 필요 없습니다 — 이메일로 받은 코드, 비밀번호 또는 2FA로 로그인합니다.

• 카메라용: 프린터와 같은 LAN에 있는 기기와 프린터에서 "LAN Mode Liveview" 활성화(설정). 전체 LAN-Only 모드와는 별개이므로 Bambu Handy 앱은 계속 작동합니다.

설치

git clone https://github.com/dylansantwani/bambu-cloud-mcp.git
cd bambu-cloud-mcp
npm install
npm run build

이 명령은 TypeScript를 dist/로 컴파일합니다. MCP 진입점은 dist/index.js입니다.

구성

MCP 클라이언트에 서버 등록

Claude Code(사용자 범위 — 모든 프로젝트에서 사용 가능):

claude mcp add bambu -s user -- node /absolute/path/to/bambu-cloud-mcp/dist/index.js

Claude Desktop — claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "bambu": {
      "command": "node",
      "args": ["/absolute/path/to/bambu-cloud-mcp/dist/index.js"]
    }
  }
}

클라이언트를 다시 시작(또는 새 세션 시작)하여 서버를 인식하게 하세요.

환경 변수

모두 선택 사항입니다:

클라이언트에서 구성 디렉터리를 설정하려면 서버 항목에 env 블록을 추가하세요:

{
  "mcpServers": {
    "bambu": {
      "command": "node",
      "args": ["/absolute/path/to/bambu-cloud-mcp/dist/index.js"],
      "env": {
        "BAMBU_MCP_CONFIG_DIR": "/absolute/path/to/config"
      }
    }
  }
}

클라우드 로그인 (원격 제어용)

대화형 로그인을 자신의 터미널에서 실행하세요(입력 프롬프트가 필요하므로 MCP 클라이언트 내에서는 실행할 수 없습니다):

npm run login

• 리전을 선택하세요(기본값: US).

• 계정 이메일을 입력하세요.

• **방법 1(이메일 코드)**을 선택하세요 — 비밀번호가 필요 없으며 일회용 코드가 이메일로 전송됩니다. 비밀번호 및 TOTP-2FA도 지원됩니다.

자격 증명은 ~/.bambu-mcp/cloud.json(모드 0600)에 저장됩니다. 비밀번호를 사용하는 경우 비밀번호는 Bambu의 로그인 엔드포인트로만 전송되며 절대 저장되지 않습니다. 다음 서버 시작 시 연결된 프린터가 자동으로 검색되어 클라우드를 통해 연결됩니다. sync_cloud_printers 도구로 언제든지 이 작업을 트리거할 수도 있습니다.

카메라 액세스 (선택 사항, LAN 전용)

카메라에는 각 프린터의 8자리 LAN 액세스 코드(프린터 화면 → Settings → WLAN)가 필요합니다. set_camera_access 도구를 통해 한 번 저장하세요(또는 어시스턴트에게 요청하세요). 프린터의 LAN IP는 상태에서 자동 감지되므로 하드코딩할 필요가 없습니다. 그런 다음 get_camera_frame이 실시간 스냅샷을 반환합니다.

사용법

서버가 등록되고 로그인한 후에는 평이한 언어로 어시스턴트에게 말하세요. 예:

• "내 Bambu 프린터를 나열하고 상태를 보여줘."

• "내 P1S의 인쇄 진행률은 어떻게 되나요?"

• "mini-1 프린터의 인쇄를 일시 정지해."

• "내 X1C의 노즐 온도를 220°C로 설정해."

• "A1의 카메라 스냅샷을 보여줘."

• "모든 프린터에서 benchy.3mf를 시작해."

• "필라멘트를 언로드한 다음 슬롯 2를 로드해."

LAN 전용 프린터를 직접 추가하려면(클라우드 계정 없이): "액세스 코드 12345678, 시리얼 01P00A123456789인 192.168.1.50의 프린터를 추가해."

작동 방식

프린터의 mode는 MQTT 클라이언트가 연결하는 방식을 결정합니다:

• LAN 모드는 사용자 이름 bblp + 프린터의 액세스 코드로 프린터 IP에 연결합니다.

• 클라우드 모드는 사용자 이름 u_<uid> + 계정 토큰으로 us.mqtt.bambulab.com(중국은 cn.)에 연결합니다.

명령 토픽(device/<serial>/request 및 /report)은 두 방식 모두 동일하므로 모든 제어 도구가 LAN에서와 동일하게 클라우드에서도 작동합니다. 파일 작업은 FTPS(basic-ftp)를 사용하고, 챔버 카메라는 프린터의 TLS 포트 6000 이미지 프로토콜을 직접 사용합니다(camera-client.ts).

src/
  index.ts            MCP server entry; registers tools, auto-connects on startup
  fleet-manager.ts    Multi-printer connection manager (LAN + cloud branches)
  mqtt-client.ts      Bambu MQTT protocol (status + all control commands)
  bambu-cloud.ts      Cloud API: login, email-code/2FA, device discovery, refresh
  cloud-store.ts      ~/.bambu-mcp/cloud.json credential store
  login-cli.ts        Interactive `npm run login`
  camera-client.ts    LAN chamber-image capture (TLS port 6000 → JPEG)
  camera-store.ts     ~/.bambu-mcp/cameras.json access-code store
  ftp-client.ts       FTPS file operations
  tools/              One file per tool group

모든 자격 증명은 ~/.bambu-mcp/(cloud.json, cameras.json, printers.json)에 로컬로 유지되며, 모드 0600으로 저장되고 git에서 무시됩니다. Bambu 자체 API와 MQTT 브로커 외에는 어디에도 전송되지 않습니다.

문제 해결

• 클라우드 로그인 403 — Bambu API가 Cloudflare 뒤에 있습니다. 잠시 기다렸다가 다시 시도하세요.

• sync_cloud_printers가 0개 프린터를 반환 — 연결된 프린터가 없는 계정으로 로그인했습니다. Bambu Handy 앱에서 사용하는 계정으로 로그인하세요.

• 카메라 ECONNREFUSED — 해당 프린터에서 "LAN Mode Liveview"가 활성화되지 않았거나 프린터가 오프라인입니다(IP는 상태에서 자동 감지됨).

• 카메라 시간 초과 — 기기가 프린터와 같은 네트워크에 있지 않습니다. 카메라는 LAN 전용입니다.

• LAN에서 connack timeout / ECONNRESET — Bambu 프린터는 로컬 MQTT 클라이언트를 하나만 허용합니다. BambuStudio / OrcaSlicer / Home Assistant를 닫고 다시 시도하세요.

기여

기여는 언제나 환영합니다 — 개발 환경 설정, 빌드 단계 및 Conventional Commits 규칙은 CONTRIBUTING.md를 참조하세요. AI 코딩 에이전트를 사용하는 경우 AGENTS.md에 저장소별 참고 사항이 있습니다.

크레딧

• LAN 제어 기반: griches/bambu-mcp — 이 프로젝트가 포크하여 기반으로 삼은 원래 MQTT 제어 계층 및 로컬 도구 모음입니다.

• 클라우드 제어, 비밀번호 없는 로그인, LAN 카메라 캡처는 이 포크에서 추가된 고유 기능입니다.

• 클라우드 프로토콜 세부 사항은 ha-bambulab / pybambu를 참고했으며, 카메라 프로토콜은 Bambu Lab 포럼에 문서화된 커뮤니티 리버스 엔지니어링을 따릅니다.

라이선스

MIT. 업스트림 베이스(griches/bambu-mcp)는 명시적인 라이선스를 게시하지 않습니다. 이 포크는 이를 눈에 띄게 표시하고 원래 추가된 기능에 MIT 라이선스를 적용합니다. 업스트림 작성자이시며 다른 처리를 원하시면 이슈를 열어 주세요.