MCP 3D Printer Server

STL 操作工具

所有 STL 工具都会将完整网格加载到内存中。修改模型的工具会在服务的临时目录中写入新文件，文件名由输入文件名加上 _scaled 等后缀构成，并返回其路径；不会修改输入文件。

get_stl_info

检查 STL 文件但不做修改。返回边界框、尺寸、中心点、顶点数和面数。

{
  "stl_path": "/path/to/model.stl"
}

scale_stl

使用 scale_factor 对模型进行等比缩放，或使用 scale_x、scale_y 和 scale_z 分轴缩放。只要提供了任一轴的值，未指定的轴就保持为 1.0。

{
  "stl_path": "/path/to/model.stl",
  "scale_factor": 1.2
}

{
  "stl_path": "/path/to/model.stl",
  "scale_x": 1.2,
  "scale_y": 1.0,
  "scale_z": 1.5
}

rotate_stl

按角度绕 X、Y 和 Z 轴旋转模型。省略的轴默认为 0。

{
  "stl_path": "/path/to/model.stl",
  "rotate_x": 0,
  "rotate_y": 0,
  "rotate_z": 90
}

translate_stl

沿 X、Y 和 Z 轴移动模型，单位为毫米。省略的轴默认为 0。

{
  "stl_path": "/path/to/model.stl",
  "translate_x": 10,
  "translate_y": 5,
  "translate_z": 0
}

extend_stl_base

在模型下方添加实体几何体，以抬高并加宽底座。extension_inches 的单位为英寸，并会转换为毫米（每英寸 25.4 mm）。

{
  "stl_path": "/path/to/model.stl",
  "extension_inches": 0.25
}

merge_vertices

合并距离小于 tolerance 的顶点（单位为毫米，默认值为 0.01）。这可以填补细小间隙，并略微简化网格。

{
  "stl_path": "/path/to/model.stl",
  "tolerance": 0.01
}

center_model

移动模型，使其包围盒的中心位于原点 (0, 0, 0)。

{
  "stl_path": "/path/to/model.stl"
}

lay_flat

找到模型最大的平面，并旋转模型，使该平面贴合 XY 平面（Z = 0）。最适用于具有明显主导平面的模型。

{
  "stl_path": "/path/to/model.stl"
}

modify_stl_section

对模型的一个部分进行缩放、旋转或平移：包围盒的 top、bottom 或 center 三分之一，或一个 custom 盒体。根据 transformation_type，value_x、value_y 和 value_z 分别表示缩放因子、角度或毫米数。

{
  "stl_path": "/path/to/model.stl",
  "section": "top",
  "transformation_type": "scale",
  "value_x": 1.5,
  "value_y": 1.5,
  "value_z": 1.5
}

custom 部分需要提供全部六个边界：

{
  "stl_path": "/path/to/model.stl",
  "section": "custom",
  "transformation_type": "rotate",
  "value_x": 0,
  "value_y": 0,
  "value_z": 45,
  "custom_min_x": -10,
  "custom_min_y": 0,
  "custom_min_z": -10,
  "custom_max_x": 10,
  "custom_max_y": 20,
  "custom_max_z": 10
}

generate_stl_visualization

渲染包含模型正面、侧面、顶部和等轴测视图的 SVG。width 和 height 用于设置每个视图的像素尺寸（默认值为 300）。

{
  "stl_path": "/path/to/model.stl",
  "width": 400,
  "height": 400
}

该 SVG 为简化示意图，并非照片级真实渲染。

打印机控制工具

每个打印机工具都接受 host、port、type 和 api_key；Bambu 打印机还会使用 bambu_serial 和 bambu_token。省略的值将回退为 PRINTER_HOST、PRINTER_PORT、PRINTER_TYPE、API_KEY、BAMBU_SERIAL 和 BAMBU_TOKEN。请将密钥保存在服务配置中，而不要在调用时传入。

每次调用的具体行为取决于后端；有关准确的 API 路由，请参阅打印机后端设置。

在所有后端上，每次开始打印和发出正向加热命令时，都会经过安全检查：服务会检查即将启动的确切 G-code，将每个加热器目标温度与硬件和材料上限进行比较，检查打印机是否就绪，并要求人工通过 MCP elicitation 确认。关闭加热器（temperature: 0）和 cancel_print 不受此检查限制。

get_printer_status

读取打印机当前状态。响应为后端自身的状态数据：Bambu 会返回温度、作业状态、进度、层数、剩余时间和 AMS 数据；OctoPrint 会返回打印机状态和温度；Klipper 只会返回 Moonraker 主机状态。

{
  "type": "klipper",
  "host": "192.168.1.50",
  "port": "7125"
}

list_printer_files

列出存储在打印机或其主机软件上的文件。在 Bambu 打印机上，会列出 cache/、timelapse/ 和 logs/ 目录。

{
  "type": "octoprint",
  "host": "192.168.1.100"
}

upload_gcode

将 G-code 上传到打印机，并可选择启动打印。对于本地文件，请传入 gcode_path；也可以传入包含内容（或本地路径）的 gcode。filename 默认为 gcode_path 的基本文件名；打印时，请使用纯文件名，以确保启动的文件正是已上传的文件。

{
  "type": "klipper",
  "host": "192.168.1.50",
  "port": "7125",
  "gcode_path": "/path/to/benchy.gcode",
  "print": true,
  "material": "PETG"
}

• 不传入 print 时，文件只会上传，不会检查或启动。
• 传入 print: true 时，会先检查实际上传的字节（所有 S 和 R 加热器目标温度、工具切换，以及硬件和材料上限），再检查打印机状态，并由人工确认后启动任务。
• 打印需要声明材料：文件中的切片器元数据（; filament_type = PLA），或 material 参数；两者不能相互矛盾。
• 在 Bambu 打印机上，文件会通过 FTPS 上传到 cache/，打印还需要指定型号（bambu_model 或 BAMBU_MODEL）。上传后自动打印仅支持 .gcode；.3mf 项目请使用 print_3mf。

start_print

启动已存储在打印机上的 G-code 文件。服务端会下载该文件，检查文件和打印机状态，请求人工确认，然后启动一个具有唯一名称且已检查的副本。此功能适用于 Bambu Lab、OctoPrint、Klipper（Moonraker）和 Duet。Repetier、Prusa 和 Creality 不支持，因为其适配器没有经过验证的下载路径；请改用 upload_gcode 并传入 print: true。

{
  "type": "octoprint",
  "host": "192.168.1.100",
  "filename": "benchy.gcode",
  "material": "PLA"
}

如果文件没有 filament_type 元数据，请传入 material。在 Bambu 打印机上，还需要指定型号，且仅支持 .gcode 文件；对于纯文件名，会在 cache/ 中查找。

cancel_print

取消当前打印任务。取消操作不受任何限制，等待启动的已检查打印任务也会一并取消。没有暂停或恢复工具；取消后无法恢复。

{
  "type": "prusa",
  "host": "192.168.1.120"
}

set_printer_temperature

设置打印机组件的目标温度。使用 bed 或 extruder；Bambu 还接受 nozzle、tool 和 tool0。OctoPrint 的喷嘴目标温度会发送到 tool0。

{
  "type": "klipper",
  "host": "192.168.1.50",
  "port": "7125",
  "component": "extruder",
  "temperature": 215,
  "material": "PLA"
}

• temperature 必须是大于或等于 0 的有限数值。0 会关闭加热器，且不受任何限制。
• 连接前会检查大于 0 的目标温度是否超过独立的硬件上限或材料上限；打印机还必须处于就绪状态，并需经人工确认。
• 喷嘴目标温度大于 0 时必须指定 material（例如 PLA、PETG 或 ABS），即使线轴没有 RFID 也必须指定。
• 在 Bambu 打印机上，加热温度大于 0 时还需要指定 bambu_model（或 BAMBU_MODEL）；喷嘴加热还需要指定 nozzle_diameter（0.2、0.4、0.6 或 0.8；默认使用 NOZZLE_DIAMETER 或 0.4）。两者都会与打印机实时状态进行核对。

Bambu 专用工具

这些工具适用于 PRINTER_TYPE=bambu（或 type: "bambu"）。请按照 Bambu Lab 设置中的说明，设置 LAN Only Mode、序列号、访问码和型号。

print_3mf

通过 FTPS 将切片后的 .3mf 项目上传到 Bambu 打印机，并通过 MQTT project_file 命令启动打印。该命令包含打印板的 G-code 路径、其 MD5、AMS 映射和校准标志。必须提供 bambu_model（或 BAMBU_MODEL）；否则，如果客户端支持 MCP 信息征询，服务端会通过该功能询问，否则返回错误。型号错误可能导致热床撞上喷嘴。

上传前，服务端会检查所选打印板的私有副本（型号、喷嘴、热床类型、材料和所有加热器目标温度）。它会将这些信息与各型号的硬件限制、材料温度上限，以及打印机最新的 MQTT 报告进行核对。报告包含打印机型号、序列号、喷嘴、状态、错误和已装入的耗材。随后由人工确认，并在发送命令前再次检查报告。

{
  "three_mf_path": "/path/to/bracket.gcode.3mf",
  "bambu_model": "p1s",
  "bed_type": "textured_plate",
  "use_ams": true,
  "ams_mapping": { "Generic PLA": 0 },
  "bed_leveling": true,
  "flow_calibration": true,
  "vibration_calibration": true,
  "layer_inspect": true,
  "timelapse": false
}

• 如果项目没有打印板 G-code，服务端会尝试使用 FULU OrcaSlicer-bambulab 或 Bambu Studio 自动切片。如果切片失败，或所选打印板仍没有 G-code，服务端会报错停止，绝不会上传原始项目。
• ams_mapping 是一个对象，其值为 AMS 槽位编号。如果省略，则使用 3MF 中嵌入的映射；如果完全没有映射，则不使用 AMS 进行打印。use_ams: false 会关闭 AMS。
• 发送命令后，服务端会监视最新报告，最长等待 15 秒（BAMBU_DISPATCH_CHECK_MS），并返回 dispatch: "started" 或 "unconfirmed"。如果固件拒绝该命令（在固件版本 01.08.05 及更高版本中，未启用 Developer Mode 时会出现 HMS 0500-0500-0001-0007），调用会失败并说明原因；已检查的文件仍保留在打印机存储中。
• nozzle_type（stainless_steel、hardened_steel、tungsten_carbide、brass）用于在必须自动切片项目时设置已安装的喷嘴。作业的喷嘴类型必须与打印机报告一致。
• bed_type 可设为 textured_plate、cool_plate、engineering_plate 或 hot_plate（默认使用 BED_TYPE，否则为 textured_plate）。它必须与打印板的热床元数据一致；因此，为其他打印板切片的文件，或缺少热床元数据的文件，只有在 bed_type 匹配后才会被接受。
• nozzle_diameter 接受 0.2、0.4、0.6 或 0.8（默认使用 NOZZLE_DIAMETER，否则为 0.4）。
• 未指定时，校准标志默认开启（延时摄影默认关闭）。
• 接受 layer_height、nozzle_temperature、bed_temperature 和 support_enabled，但不会应用这些设置：它们已写入切片文件。请在切片器中更改。
• 成功响应表示命令已发送，并不表示打印已顺利启动。之后请检查打印机状态。

check_fulu_orca_setup

检查 FULU OrcaSlicer-bambulab 安装：可执行文件、平台运行时载荷、安装和验证命令，以及可选的 BambuNetwork 桥接握手。路径默认为服务端环境中的路径；请参阅检查安装设置。

{
  "platform": "darwin",
  "run_bridge_probe": true
}

bridge_command，以及在设置 run_bridge_probe: true 时使用的 slicer_path、plugin_dir 或 runtime_dir，都需要 MCP_ALLOW_EXECUTABLE_ARG=1。

fulu_bambu_network_rpc

调用一个 FULU BambuNetwork 桥接方法进行诊断。默认允许 bridge.handshake、bridge.runtime_info 和 net.get_user_print_info 等只读方法。Agent 和会话设置方法需要设置 allow_mutating_method: true。原始打印方法（例如 net.start_print）、打印机消息（net.send_message）、文件传输和未知方法都会被拒绝，因为这些操作会绕过打印安全门；请使用 print_3mf 进行打印。bambu_model 仅供参考。请参阅 桥接 RPC。

{
  "method": "bridge.handshake"
}

桥接命令来自 FULU_BAMBU_BRIDGE_COMMAND；每次调用单独指定 bridge_command 需要设置 MCP_ALLOW_EXECUTABLE_ARG=1。

切片工具

有关切片器类型、配置文件和故障排除，请参阅切片指南。最可预测的方式是在切片器的图形界面中自行切片文件，然后上传结果。

使用已配置的切片器对 STL 或 3MF 进行切片，并返回输出路径：PrusaSlicer、Slic3r、通用 OrcaSlicer 和 CuraEngine 会输出 G-code；Bambu 兼容路径会输出切片后的 .3mf。

Bambu 兼容路径适用于 Bambu Studio、FULU OrcaSlicer-bambulab，以及调用时传入 bambu_model 的 OrcaSlicer：

• 机器预设始终取自 bambu_model（如果缺少，则会询问；也可使用 BAMBU_MODEL）和 nozzle_diameter（默认使用 NOZZLE_DIAMETER，否则为 0.4）。所选切片器安装中必须存在完全匹配的 <model> <diameter> nozzle 预设。切片器运行前，会解析其 inherits 和 include 链。
• slicer_profile（或 SLICER_PROFILE）仅作为工艺配置文件。传入 machine;process 列表将被拒绝，并会显示相关说明。
• 如果安装的切片器有对应预设，切片支持 p1s、p1p、p2s、x1c、x1e、a1、a1mini、h2d、h2s 和 h2c。打印仍只支持 BAMBU_MODEL 中的七种型号。
• 输出必须包含非空的 Metadata/plate_<n>.gcode。发生故障时，操作会停止，并显示切片器的退出代码或信号、输出末尾内容以及切片相关建议。

{
  "stl_path": "/path/to/phone-case.stl",
  "slicer_type": "bambustudio",
  "bambu_model": "p1s",
  "nozzle_diameter": "0.4",
  "bed_type": "textured_plate",
  "load_filaments": "/path/to/filaments/tpu-95a-hf.json",
  "arrange": true,
  "orient": false
}

Bambu 兼容路径的选项：

通用切片器使用各自的配置文件格式：PrusaSlicer 和 Slic3r 加载一个导出的配置文件；通用 OrcaSlicer 使用 machine.json;process.json，后面可选接 |filament.json。slicer_type、slicer_profile 和 filament_profile 的备用值分别为 SLICER_TYPE、SLICER_PROFILE 和 FILAMENT_PROFILE。切片器可执行文件由 SLICER_PATH 指定；要在单次调用中使用 slicer_path，需设置 MCP_ALLOW_EXECUTABLE_ARG=1。请参阅切片指南。

slice_with_template

使用本地模板注册目录中的命名模板切片 STL 或 3MF。模板提供工艺设置；机器预设仍由 bambu_model 和 nozzle_diameter 提供。它接受与 slice_stl 相同的参数，调用中显式指定的 slicer_profile 会覆盖模板。

{
  "stl_path": "/path/to/bracket.stl",
  "template_name": "p1s-petg-strong",
  "bambu_model": "p1s"
}

list_templates

列出模板注册目录、BAMBU_TEMPLATE_DIR（默认为 ~/Sync/bambu/templates）或 template_dir 中保存的切片模板（.3mf、.json、.config）。

{}

save_template

将本地 .3mf、.json 或 .config 文件复制到模板注册目录。template_name 默认为不带扩展名的源文件名。

{
  "source_path": "/path/to/p1s-petg-strong.3mf",
  "template_name": "p1s-petg-strong"
}

get_slice_settings

读取 3MF、提取后的 project_settings.config 或配置文件 JSON 中的切片设置，而不执行切片：层高、填充、壁厚、支撑、裙边、热床、打印机和耗材。传入 source_path，或传入 template_name 以读取已保存的模板。

{
  "template_name": "p1s-petg-strong"
}

confirm_temperatures

报告 G-code 文件中的所有加热器目标温度：S 和 R 形式、指定工具的目标温度、RepRapFirmware G10/M568，以及 Klipper SET_HEATER_TEMPERATURE。只有当预期的 extruder_temp 或 bed_temp 等于文件中的最高目标温度时，才会匹配；结果会返回该最高温度 peak。此工具为只读；打印工具会执行各自的安全检查。

{
  "gcode_path": "/path/to/model.gcode",
  "extruder_temp": 240,
  "bed_temp": 80
}

process_and_print_stl

为 STL 添加底座、切片，并通过与 upload_gcode 和 print_3mf 相同的打印检查流程进行打印，包括人工确认。如果传入 extruder_temp 或 bed_temp，每个值都必须等于切片任务的最高目标温度（所有工具的 S 和 R 形式）；如果不匹配，会在上传任何内容之前停止。如果切片后的 G-code 没有 filament_type 元数据，请传入 material。在使用 Bambu 兼容切片器的 Bambu 打印机上，切片后的 .3mf 会经过 print_3mf 检查，并且必须提供打印机型号。

{
  "stl_path": "/path/to/model.stl",
  "extension_inches": 0.1,
  "extruder_temp": 210,
  "bed_temp": 60,
  "material": "PLA",
  "type": "octoprint",
  "host": "192.168.1.100"
}

如果想在切片文件提交打印确认之前先检查文件，请分别使用 slice_stl、confirm_temperatures 和 upload_gcode。

高级工具

Blender MCP

通过 BLENDER_MCP_COMMAND（例如，uvx 的完整路径）和 BLENDER_MCP_ARGS（例如 ["mcp-for-blender"]）连接标准 stdio Blender MCP 服务。mcp-for-blender 项目此前以 blender-mcp 名称发布，该名称仍可作为兼容包装器使用。在 Blender 中安装并启用其插件，然后启动插件连接。Blender 和此服务必须能够读取相同的本地文件。即使未配置 Blender，打印机工具也能正常工作。Agent 工作期间请保持 Blender 打开：该插件不会在后台模式下运行。有关设置、单位以及从头到尾为新手机改造手机壳的完整示例，请参阅 Blender 指南。

blender_mcp_status

检查 Blender MCP 配置。设置 connect: true 后，它会启动已配置的服务、完成初始化，并按名称和摘要列出其工具。传入 tool_names 可获取即将调用的工具的完整输入架构（include_schemas: true 会返回所有架构，内容较多）。连接成功并不能证明 Blender 内部的插件正在运行；请通过 blender_mcp_call 调用 get_scene_info 进行检查。

{
  "connect": true,
  "tool_names": ["execute_blender_code"]
}

blender_mcp_call

调用 Blender MCP 服务所公布的工具（例如 get_scene_info 或 execute_blender_code），并传入与其已发现架构相符的参数。此工具会返回完整的 MCP 结果，包括图像和错误。调用可能会更改当前活动的 Blender 场景，且绝不会自动重试。远程工具要求提供 user_prompt 时，请保留用户自己的原话。

{
  "tool_name": "get_scene_info",
  "arguments": { "user_prompt": "Inspect the scene before preparing a print." }
}