Bambu Studio (unofficial)

非官方 Bambu MCP

非官方社区项目。 与 Bambu Lab 无关，未获其认可或支持。 “Bambu Lab”、“Bambu Studio”、“Bambu Connect”和“Bambu Handy”是其各自所有者的商标。

一个 MCP 服务，让 AI 助手（Claude Code、Claude Desktop 或任何 MCP 客户端）使用你已安装的官方 Bambu Studio 构建、编辑、切片、检查和校准 Bambu Studio 项目，并在本地网络上读取打印机的状态。

你只需提出要求，它就会处理切片工作：

• “新建 P1S 项目：一个 20 mm 的立方体，以及一个黑色 2 mm 标签，上面用白色写着‘DANI’。”
• “打开 ~/Downloads/Gnome 3 Color.3mf，再添加一个有两个侏儒的新打印板，然后将其转换为 A1 mini 格式。”
• “我的 AMS 2 号槽里有 eSUN PLA Basic：为它创建一个预设和用于校准的测试打印模型。”
• “开始打印这个 20 小时的打印板之前：哪些部件可能会脱落？”
• “一个销钉在第 4 层脱落了，我跳过了它：帮我创建一个项目，只重新打印这个销钉，并加上裙边。”
• “打印进展如何？正在使用哪个线轴？”

_{一段真实会话，加速播放：每次工具调用、结果和图像都通过 MCP 来自服务端；演示中只有请求是专门编写的（scripts/make_demo.py）。}

功能

区域	可执行的操作
项目	创建项目，或打开任何由 Bambu Studio（2.x 和较早的 1.6/1.7 文件）保存或从 MakerWorld / Printables 下载的 .3mf：涂装颜色、修改器、对象设置、实例和打印板都会保留。保存时绝不会覆盖原文件。
打印机	Bambu Studio 2.8 支持的全部 14 款 Bambu Lab 打印机，均经过端到端测试（项目、排列、切片、打印文件）：A1 mini、A1、A2L、P1P、P1S、P2S、X1、X1 Carbon、X1E、H2S，以及双喷嘴 H2D、H2D Pro、H2C 和 X2D（耗材会自动分配给喷嘴，与 Bambu Studio 的行为相同）。切换打印机后，对象会针对新打印平台重新排列。新项目使用你在 Bambu Studio 中为该打印机选定的构建板。
耗材	包含预设和颜色的 AMS 槽位，也包括你自己的用户预设。use_ams_filaments 会读取 AMS 当前装载的耗材。
打印板和对象	导入 STL、OBJ、3MF；创建方盒、圆柱体、圆锥体、球体和文本（底座可使用另一种颜色）。移动、旋转、缩放、镜像、平放、自动定向（尽量减少支撑并确保能放在打印平台上）、复制、用副本填满打印板、将对象拆分成多个对象或部件、将多个对象合并成一个对象、执行网格布尔运算（孔、并集、交集）并保留涂装颜色，为每个对象或部件指定耗材，设置对象级参数，检查封闭实体。工作过程中对象 ID 保持不变。
排列	按从上方看到的真实轮廓执行 arrange，包括裙边和裙边耳，便于形状相互嵌套（Bambu Studio 自带的排列功能使用凸包）。可设置间距、旋转步长、每块打印板使用一种材料、校准角、沿 Y 轴对齐，以及为擦料塔预留空角；可排列一块打印板、选定对象或全部对象；可均匀分配到指定数量的打印板，或尽量减少打印板数量。如果对象放不下，则不会移动任何对象，并会说明剩余对象。
切割	在任意平面上使用 cut_object，并添加类似 Bambu Studio 切割工具的连接件：插接件（带间隙的销和孔）、定位销（两件上都有孔，另有独立销钉）或燕尾榫；形状可为圆形、方形或六边形，可为直型或锥形，可自动放置或按指定位置放置，并会在部件较薄处缩短深度。切割后的部件会排好以便打印：销始终朝上。
修改器	盒状或圆形部件：可设置具有独立参数的修改器（例如“顶部 5 mm 的填充率为 100 %”）、负向部件（用于磁铁和螺丝的孔）、支撑阻挡器和支撑强制器。
设置	读取或更改任何 Bambu Studio 设置；适用时可按耗材槽位设置。当某个值不适用时会发出警告（例如，纹理板温度不适用于光滑板）。
预设	将项目更改保存为 Bambu Studio 用户预设：耗材（save_filament_preset）、工艺和打印机预设；也可直接更改已有预设（edit_preset），并列出、重命名和删除预设，每次都会创建备份副本。系统会按 Bambu Studio 的方式检查并写入数值（适用时按喷嘴变体分别写入），并为更改添加时间戳，以供 Bambu Studio 云同步。存放在 Bambu 云中的预设只能从 Bambu Studio 删除，答复会说明操作方法。
文本和徽标	add_relief：在对象的任意表面添加文本或 SVG 徽标，可凸起（也可使用另一种颜色）或雕刻，也支持贴合曲面（在精细网格上测量下方表面，并将形状包覆其上，同时保持其沿表面的尺寸）。add_shape('svg')：将徽标作为对象放置，底座可使用另一种颜色。可读取 SVG 路径、形状、变换、填充规则和描边。
测量	measure_object：尺寸和位置、每个部件的体积和表面积、打印平台上的占用面积、打印件各部件之间的间隙、薄于喷嘴线宽的壁厚（位置和高度），以及任意高度处的横截面：杆件的长度和厚度、孔的宽度。measure_between：两个对象或部件之间的间距、中心位置和重叠情况。会在副本上测量密集网格，精度为 0.005 mm（240 万个三角形的模型约需 9 s）。
高度范围和打印板	set_height_range：为对象一定高度范围设置参数，类似 Bambu Studio 的高度范围修改器：底部填充率为 100 %、在细节处使用更精细的层（可变层高）、某个高度范围使用另一种耗材（按高度着色）。打开文件中的可变层高和高度范围都会保留。set_plate_settings：按打印板设置构建板、打印顺序（按对象）、首层耗材顺序、螺旋花瓶模式和擦料塔位置。
涂装	paint_object：按高度范围和／或朝向指定方向的表面（顶部、侧面、悬垂面等）涂装颜色、支撑（或无支撑）、接缝和毛绒表面，并保留锐利边缘。通过切片后的 G-code 验证：颜色范围会在边界处切换耗材，涂装的支撑会出现在涂装位置。
清料量	get_purge_volumes / set_purge_volumes：设置每对槽位之间的清料量和倍率，与 Bambu Studio 对话框中的设置相同；打开文件中的数值会保留。
切片	使用 Bambu Studio 命令行：按打印板显示耗材所需时间、克数和成本、耗材更换次数、暂停、层数和警告。会跳过空打印板。
预览	查看打印板图片（等轴测或俯视、缩放、涂装颜色、对象标签）以及任意已切片层的图片，便于助手检查自己的操作。
打印风险	check_print_risks：检测高而窄的部件、没有裙边且底部支撑面积很小或很窄的部件、不适用于构建板的耗材、在较长打印板上并排的高部件，以及在原位打印模型上会焊死活动关节的完整裙边。
裙边耳	add_brim_ears：仅在原位打印和可动模型的细窄末端（手指、脚趾）添加小型圆形裙边耳，可自动放置在远离关节间隙和其他部件的位置，也可按指定位置放置。使用 Bambu Studio 的涂装裙边，并通过切片后的首层进行检查。
重新打印	reprint_objects：创建仅包含打印失败部件的新项目，并保留相同设置，同时添加裙边。
校准	任意耗材均可进行温度塔、流量测试（第 1 和第 2 轮）、压力提前量塔、最大体积流量测试、回抽测试、VFA 测试（壁面速度）和首层测试。可将结果保存为 Bambu Studio 耗材预设：新耗材会获得自己的 ID，类似 Bambu Studio 的创建耗材，因此可为 AMS 槽位选择该耗材；之后更新预设时会保留此 ID。
层操作	在指定高度暂停（放置磁铁、螺母）、更换耗材，或执行任意 G-code。
打印	send_to_printer 会为某块打印板生成打印文件，并在 Bambu Studio（或 Bambu Connect）中打开，准备就绪后即可打印：你只需检查 AMS 映射并点击“打印”。
开发者模式（局域网打印农场）	适用于启用了开发者模式的局域网模式打印机，Bambu 固件允许其他程序发送命令：send_to_printer(via='lan') 会上传打印板并开始打印，skip_objects 会跳过正在进行的打印任务中的部件，ams_load / ams_unload 会装入／卸出耗材。每项操作都会先请求确认：首次调用不会发送任何内容，只会提供一个确认码。在普通云模式下，打印机会拒绝这些操作，答复也会说明原因。
打印机状态	printer_status（只读，仅限本地网络）：状态、进度、温度、带湿度信息的 AMS 托盘、已跳过的对象和警告（正在进料的线轴未知、长时间打印时启用了运动模式、读数看起来已过时）。
摄像头和 SD 卡	printer_camera：查看当前打印板的照片，便于助手了解打印进度。printer_files / download_printer_file：查看延时摄影视频（含最后一帧）和过往打印文件。delete_printer_files：释放 SD 卡空间，仅在你确认准确的文件列表后才会执行。云模式下也可使用。
全部 87 个工具及其参数：docs/TOOLS.md。

测试环境

真实硬件：macOS、Bambu Studio 2.8.2、一台配有两个 AMS 单元的 P1S，处于普通云端模式：

• 通过真实 MCP 客户端测试了每个工具，使用从头创建的项目以及从 MakerWorld / Printables 下载的项目 （已涂色的 6 色模型、多部件装配、3 个平台的项目，以及来自 Bambu Studio 1.6 和 1.7 的文件）；
• 已打印：两个第三方耗材（eSUN PLA Basic 黑色和白色）的温度塔和流量测试；其预设通过该服务创建并调校；还测试了将打印任务交给 Bambu Studio，以及打印期间的实时状态。

压力提前量塔、最大体积速度测试和回抽测试已通过切片检查（并检查了 G-code），但尚未打印。

Windows 和 Linux：每次 main 有更改时，CI 都会安装 Bambu Studio 2.8.2（Windows 上使用便携版 zip，Debian 13 上使用 AppImage），运行完整测试套件（包括切片和打印文件），并进行冒烟测试。单元测试使用 Python 3.10 和 3.13，在 Windows、macOS 和 Linux 上运行。在 Linux 上，AppImage 使用系统中的 FFmpeg 7 和 WebKitGTK 4.1（Debian 13、Ubuntu 24.10 或更高版本）；如果 Bambu Studio 位于其他位置，请设置 BAMBU_STUDIO_EXE。

打印机：Bambu Studio 2.8 支持的全部 14 款 Bambu Lab 打印机都已通过 MCP 从新建项目测试到生成打印文件（A1 mini、A1、A2L、P1P、P1S、P2S、X1、X1 Carbon、X1E、H2S、H2C、H2D、H2D Pro、X2D）；只有 P1S 实际打印过。Developer Mode 工具已在云端模式下对打印机进行检查（按预期拒绝操作），但从未在 Developer Mode 下启动打印。

打印与打印机

Bambu 固件（2025 年及之后版本）只有在打印机处于开启 Developer Mode 的仅局域网模式时，才接受其他程序发来的命令；这会关闭云端服务和 Bambu Handy。普通云端模式下，打印机会拒绝这些命令，因此该服务：

• 读取打印机状态（云端模式下允许），使用 Bambu Studio 已保存的 LAN 访问码；
• 将打印任务交给 Bambu Studio 或 Bambu Connect，由你按下 Print；
• 云端模式下不会启动打印、设置 AMS 槽位或跳过对象：这些操作由你在 Bambu Studio、Bambu Handy 或打印机上完成。对于处于开启 Developer Mode 的仅局域网模式下的打印机（打印农场），该服务可以执行这些操作，但始终需要你使用它提供的代码确认（见上方的 Developer Mode 行）。

更多信息见 docs/printing.md。

快速开始

要求：uv 和 Bambu Studio。该软件包来自 PyPI：uvx 会在首次运行时下载软件包（如果你没有 Python 3.10+，也会一并下载），因此无需手动克隆或安装。

这是一个标准的 MCP 服务（stdio），任何能够运行本地服务的 MCP 客户端都可以使用。该服务使用 Claude Code 开发和测试；下方其他客户端也在各自的配置文件中使用相同的命令。

Claude Code

claude mcp add bambu -- uvx unofficial-bambu-mcp

Claude Desktop（claude_desktop_config.json）、Cursor（~/.cursor/mcp.json）、Windsurf （~/.codeium/windsurf/mcp_config.json）、Gemini CLI（~/.gemini/settings.json）：

{
  "mcpServers": {
    "bambu": {
      "command": "uvx",
      "args": ["unofficial-bambu-mcp"]
    }
  }
}

OpenAI Codex CLI（~/.codex/config.toml）：

[mcp_servers.bambu]
command = "uvx"
args = ["unofficial-bambu-mcp"]

VS Code（GitHub Copilot Agent 模式，.vscode/mcp.json）：

{ "servers": { "bambu": { "type": "stdio", "command": "uvx", "args": ["unofficial-bambu-mcp"] } } }

• 如果桌面应用找不到 uvx（spawn uvx ENOENT），请将其完整路径设为命令：运行 which uvx 即可查看。
• uvx 会保留下载的版本：改用 unofficial-bambu-mcp@latest 即可获取新版本。
• 从克隆的仓库运行（用于开发）：uv run --directory /path/to/unofficial-bambu-mcp unofficial-bambu-mcp。
• ChatGPT 应用只连接远程 MCP 服务，而该服务必须运行在装有 Bambu Studio 的计算机上。

然后提问：“我安装的 Bambu Studio 是什么版本？你可以使用哪些打印机？”

配置（可选）

变量	默认值	含义
UBMCP_DIR	~/Documents/unofficial-bambu-mcp	项目、切片文件和打印文件的保存位置
BAMBU_STUDIO_EXE	自动检测	Bambu Studio 可执行文件的路径
BAMBU_STUDIO_DATA	自动检测	Bambu Studio 数据文件夹（包含 system/ 和 user/）
BAMBU_STUDIO_RESOURCES	自动检测	Bambu Studio 资源文件夹（包含 profiles/），适用于特殊的 Linux 安装
UBMCP_PRESET_BACKUPS	~/.config/unofficial-bambu-mcp/preset-backups	用户预设被更改、重命名或删除之前的备份保存位置
BAMBU_PRINTER_SERIAL、BAMBU_PRINTER_ACCESS_CODE、BAMBU_PRINTER_IP	来自 Bambu Studio	printer_status 使用的打印机；若不希望从 Bambu Studio 读取，可设置这些变量

工作原理

Bambu Studio 没有插件或脚本 API。此服务会处理项目文件（.3mf，即 Bambu Studio 保存的格式），并调用 Bambu Studio 命令行进行切片。预设从你的安装中读取，并按照应用程序的方式展开。详情请参阅 docs/how-it-works.md。

• 与应用程序保持同步。 open_in_bambu_studio 会在应用程序中显示项目；如果你在其中更改项目并保存，服务会在下一次执行命令时重新读取（并在双方都有更改时告知你）。
• 安全处理你的文件。 绝不会覆盖任何内容：保存时会添加 -2、-3……；打开的文件会作为副本读取。更改、重命名或删除预设前，会先创建备份。
• 轻量。 依赖 numpy、shapely、manifold3d、fonttools 和 Pillow。本仓库不附带任何 Bambu 配置文件：预设来自你的安装（对于预设未包含的设置，服务只保留默认值）。
• 你的打印机由你掌控。 需要时才会从 Bambu Studio 读取局域网访问码，且绝不会复制到其他位置。请参阅 SECURITY.md。

指南

• 校准耗材：分步说明，并介绍每次测试打印时需要观察的内容
• 打印与打印机状态
• 故障排除
• 工作原理
• 通过 AI 助手驱动封闭式切片器：关于设计和测试的技术说明

限制

• 双喷嘴打印机（H2D、H2C、X2D）：耗材会像 Bambu Studio 的默认设置那样自动分配到喷嘴；目前还无法手动为每种耗材选择喷嘴。
• 打印机摄像头适用于 P1 和 A1 打印机（X1 和 H2 通过 RTSP 传输，暂不支持）。
• 首层测试不会保留涂装颜色。
• Bambu Studio 打开项目时会重新切片；如需在应用程序中查看已切片且可直接打印的构建板，请使用 send_to_printer。

路线图

• 网格简化与修复；双喷嘴打印机上每种耗材所用的喷嘴；X1/H2 摄像头
• 在切片器内部建立实时桥接，并向 OrcaSlicer 和 Bambu Studio 提交提案

贡献与支持

提交错误报告、想法和拉取请求：GitHub Issues。请附上你的操作系统、Bambu Studio 版本、打印机型号，以及（如果可以）导致问题的 .3mf 文件。请参阅 CONTRIBUTING.md。

作者：Daniele Finocchiaro — danielefinocchiaro.com。如果它为你节省了打印耗材和时间：请我喝杯咖啡。

许可证

本代码采用 MIT 许可证。Bambu Studio 配置文件从你的安装中读取，不会重新分发。