MCP 3D 打印服务器

描述

这是一个允许 MCP 用户连接到以下 3D 打印机 API 端点的服务器：

• OctoPrint
• Klipper (Moonraker)
• Duet
• Repetier
• Bambu Labs
• Prusa Connect
• Creality/Ender

该服务器是一个模型上下文协议（MCP）服务器，用于将 Claude 与 3D 打印机管理系统连接起来。它允许 MCP 通过各种打印机管理系统的 API 与 3D 打印机交互，例如 OctoPrint、Klipper（通过 Moonraker）、Duet、Repetier 和 Bambu Labs 打印机。

资源使用说明： 该 MCP 服务器包括高级的 3D 模型操作功能，在处理大型 STL 文件时可能会占用大量内存。请参阅“限制和注意事项”部分以获取有关内存使用和性能的重要信息。

功能

• 获取打印机状态（温度、打印进度等）
• 列出打印机上的文件
• 上传 G-code 文件到打印机
• 开始、取消和监控打印任务
• 设置打印机温度
• 高级 STL 文件操作：
  • 扩展底座以提高附着力
  • 统一或沿特定轴缩放模型
  • 绕任意轴旋转模型
  • 平移（移动）模型
  • 修改 STL 文件的特定部分（顶部、底部、中心或自定义）
• 全面的 STL 分析，提供详细的模型信息
• 生成多角度的 STL 文件 SVG 可视化
• 实时报告长时间操作的进度
• 错误处理和详细诊断
• 切片 STL 文件以生成 G-code
• 确认 G-code 文件中的温度设置
• 完整的端到端工作流程，从 STL 修改到打印
• 在 Bambu Lab 打印机上直接打印 .3mf 文件（通过 MQTT 命令）
• 读取 Bambu Studio 预设文件（打印机、耗材、过程）作为资源

安装

先决条件

• Node.js 18 或更高版本
• npm 或 yarn

从 npm 安装

npm install -g mcp-3d-printer-server

从源代码安装

git clone https://github.com/dmontgomery40/mcp-3d-printer-server.git
cd mcp-3d-printer-server
npm install
npm link  # 使命令全局可用

使用 Docker 运行

您还可以使用 Docker 和 Docker Compose 在容器化环境中运行服务器。

1. 确保已安装 Docker 和 Docker Compose。
2. 将 .env.example 复制为 .env 并配置您的设置。
3. 构建并运行容器：
   bash 复制代码

   docker-compose up --build -d

在 Docker 中使用切片器

请注意，默认的 Docker 设置无法直接使用主机上安装的切片器。由于主机和容器之间的操作系统和库差异，将切片器可执行文件直接从主机挂载到容器是不可靠的。

推荐的方法是在 Docker 镜像内部安装您喜欢的切片器。这使得容器自给自足。

为此，您需要修改 Dockerfile。以下是如何添加 PrusaSlicer 或 OrcaSlicer 的概念示例（具体命令可能因切片器、其依赖项和当前 Alpine 包而异）：

# ... 其他 Dockerfile 命令 ...

# 示例：安装 PrusaSlicer 或 OrcaSlicer（根据需要调整命令）
# 首先检查 Alpine 包仓库（例如，apk add prusaslicer 或 apk add orcaslicer）
# 如果不可用，下载并手动安装（例如 AppImage）：
# RUN apk add --no-cache fuse # AppImages 可能需要 FUSE
# RUN wget https://example.com/path/to/OrcaSlicer_Linux_Vxxxx.AppImage -O /usr/local/bin/orcaslicer && \
#     chmod +x /usr/local/bin/orcaslicer

# 在 docker-compose.yml 或运行时相应地设置 SLICER_PATH 环境变量
# 已安装可执行文件的示例：
ENV SLICER_PATH=/usr/local/bin/orcaslicer 

# ... 其余 Dockerfile ...

修改 Dockerfile 后，重新构建镜像（docker-compose build）。您还需要确保 .env 文件或 docker-compose.yml 中的 SLICER_PATH 环境变量指向容器内的正确路径（例如 /usr/local/bin/orcaslicer）。同时设置 SLICER_TYPE 为 orcaslicer。

对于未预先包含特定切片器表示歉意，但由于有多种切片器（PrusaSlicer、OrcaSlicer、Cura 等）和配置可用，预先安装一个会不必要地增加许多用户的镜像大小。如果某个特定切片器成为非常普遍的需求，我当然会在未来的版本中考虑添加官方支持。

配置

在运行服务器的目录中创建一个 .env 文件或设置环境变量：

# 打印机管理系统认证所需
API_KEY=your_api_key_here

# 默认打印机连接设置
PRINTER_HOST=localhost
PRINTER_PORT=80 # 非 Bambu HTTP API 的端口
PRINTER_TYPE=octoprint  # 选项：octoprint, klipper, duet, repetier, bambu, prusa, creality

# 可选：临时文件目录
TEMP_DIR=/path/to/temp/dir

# Bambu Labs 特定配置
BAMBU_SERIAL=your_printer_serial # Bambu 必需
BAMBU_TOKEN=your_access_token    # Bambu 必需

# 切片器配置（用于 slice_stl 工具）
SLICER_TYPE=prusaslicer  # 选项：prusaslicer, cura, slic3r, orcaslicer
SLICER_PATH=/path/to/slicer/executable
SLICER_PROFILE=/path/to/slicer/profile

# 可选：Bambu Studio 用户配置目录路径（用于加载预设）
# macOS 示例：/Users/your_user/Library/Application Support/BambuStudio/user/YOUR_USER_ID
# Windows 示例：C:\Users\your_user\AppData\Roaming\BambuStudio\user\YOUR_USER_ID
# Linux 示例：/home/your_user/.config/BambuStudio/user/YOUR_USER_ID
BAMBU_STUDIO_CONFIG_PATH=

与 Claude Desktop 一起使用

1. 编辑您的 Claude Desktop 配置文件：

{
  "mcpServers": {
    "3dprint": {
      "command": "mcp-3d-printer-server",
      "env": {
        "API_KEY": "your_api_key_here",
        "PRINTER_HOST": "your_printer_ip",
        "PRINTER_TYPE": "octoprint"
      }
    }
  }
}

2. 对于 Bambu Labs 打印机：

{
  "mcpServers": {
    "3dprint": {
      "command": "mcp-3d-printer-server",
      "env": {
        "PRINTER_HOST": "your_printer_ip",
        "PRINTER_TYPE": "bambu",
        "BAMBU_SERIAL": "your_printer_serial",
        "BAMBU_TOKEN": "your_access_token"
      }
    }
  }
}

3. 重启 Claude Desktop
4. 通过 Claude 连接到您的打印机

支持的打印机管理系统

OctoPrint

OctoPrint 是一个流行的 3D 打印机 Web 界面。它提供了用于控制打印机的 REST API。

• 默认端口：80（http）或 443（https）
• 认证：需要 API 密钥

Klipper（通过 Moonraker）

Klipper 是一种与 Moonraker API 服务器配合使用的 3D 打印机固件。

• 默认端口：7125
• 认证：取决于您的 Moonraker 配置

Duet

Duet 是一款带有自己 Web 界面（DuetWebControl）的 3D 打印机控制板。

• 默认端口：80（http）或 443（https）
• 认证：取决于您的 Duet 配置

Repetier

Repetier-Server 是一种 3D 打印机主机软件。

• 默认端口：3344
• 认证：需要 API 密钥

Bambu Labs

Bambu Lab 打印机使用 MQTT 进行状态和控制，使用 FTP 进行文件操作。

• 认证：需要序列号和访问令牌（设置 BAMBU_SERIAL 和 BAMBU_TOKEN）
• 要求：打印机必须在同一网络上或启用云连接
• 兼容：X1C、P1S、P1P、A1 和其他 Bambu Lab 打印机

查找您的 Bambu 打印机序列号和访问令牌

要连接到您的 Bambu Lab 打印机，您需要两样东西：

1. 打印机序列号：

   • 查看打印机背面或底部的标签，上面有一个序列号（通常以“01P”或“01A”开头，后跟数字/字母）
   • 或者，打开 Bambu Studio，连接到您的打印机，进入设备 > 设备管理，并查看打印机信息

2. 访问令牌：

   • 访问令牌是直接连接到打印机所需的安全代码
   • 对于 P1 系列打印机：进入触摸屏，选择设置 > 网络 > LAN 模式，您将看到访问码
   • 对于 X1 系列打印机：进入触摸屏，选择设置 > 网络 > LAN 模式，并启用 LAN 模式以查看访问码
   • 对于 A1 Mini：使用 Bambu Handy 应用连接到您的打印机，然后进入设置 > 网络 > LAN 模式

注意：如果您的打印机不在同一本地网络上或找不到访问令牌，您可能需要更新打印机的固件到最新版本以启用 LAN 模式。

Bambu 通信说明（MQTT & FTP）

• MQTT： 该服务器基于社区发现（例如 OpenBambuAPI）使用本地 MQTT 协议（端口 8883，TLS）发送命令，例如开始打印和取消任务。
• FTP： 文件列表和上传目前依赖于打印机上运行的 FTP 服务器（通过 bambu-js 库助手）。注意：此 FTP 连接可能基于当前库的限制，是不安全的（纯 FTP）。请了解您的网络安全情况后再使用。

Prusa Connect

Prusa Connect 是 Prusa 自己的基于云的解决方案，用于管理他们的打印机。

• 默认端口：80（http）或 443（https）
• 认证：需要 API 密钥
• 兼容：Prusa MK4、Prusa Mini、Prusa XL 和其他具有 Prusa Connect 功能的 Prusa 打印机

设置 Prusa Connect

1. 确保您的 Prusa 打印机已更新到最新固件
2. 将您的打印机连接到 Wi-Fi 网络
3. 创建 Prusa Connect 帐户并注册您的打印机
4. 从 Prusa Connect Web 界面的设置 > API 访问下生成 API 密钥

Creality Cloud

Creality Cloud 是 Creality 的打印机管理系统。

• 默认端口：80（http）或 443（https）
• 认证：需要 Bearer 令牌
• 兼容：Ender 系列、CR 系列和其他具有网络功能的 Creality 打印机

设置 Creality Cloud

1. 在您的移动设备上安装 Creality Cloud 应用
2. 创建帐户并添加您的打印机
3. 启用打印机的本地网络访问
4. 从 Creality Cloud 应用的设置 > 开发者选项下生成令牌

可用工具

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

{
  "stl_path": "/path/to/file.stl",
  "extension_inches": 2
}

{
  "stl_path": "/path/to/file.stl",
  "scale_factor": 1.5
}

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

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

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

{
  "stl_path": "/path/to/model.stl",
  "tolerance": 0.01 // 可选，默认 = 0.01mm
}

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

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

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

{
  "stl_path": "/path/to/file.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
}

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

{
  "stl_path": "/path/to/file.stl",
  "slicer_type": "prusaslicer",
  "slicer_path": "/path/to/prusaslicer",
  "slicer_profile": "/path/to/profile.ini"
}

{
  "gcode_path": "/path/to/file.gcode",
  "extruder_temp": 200,
  "bed_temp": 60
}

{
  "stl_path": "/path/to/file.stl",
  "extension_inches": 2,
  "extruder_temp": 200,
  "bed_temp": 60,
  "host": "192.168.1.100",
  "type": "octoprint",
  "api_key": "YOUR_API_KEY"
}

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

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

{
  "host": "192.168.1.100",
  "type": "octoprint",
  "api_key": "YOUR_API_KEY",
  "filename": "my_print.gcode",
  "gcode": "G28\nG1 X100 Y100 Z10 F3000\n...",
  "print": true
}

{
  "host": "192.168.1.100",
  "type": "octoprint",
  "api_key": "YOUR_API_KEY",
  "filename": "my_print.gcode"
}

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

{
  "host": "192.168.1.100",
  "type": "octoprint",
  "api_key": "YOUR_API_KEY",
  "component": "extruder",
  "temperature": 200
}

{
  "three_mf_path": "/path/to/your_model.3mf",
  "host": "your_bambu_ip", // 如果默认设置，则可选
  "bambu_serial": "YOUR_SERIAL", // 如果默认设置，则可选
  "bambu_token": "YOUR_TOKEN", // 如果默认设置，则可选
  // 可选覆盖：
  "use_ams": true, // 默认：true
  "ams_mapping": [0, 1, 2, 3], // AMS 插槽索引数组
  "bed_leveling": true, // 默认：true
  "flow_calibration": false, // 默认：false
  "vibration_calibration": false, // 默认：false
  "timelapse": false // 默认：false
}

可用资源

Claude 示例命令

以下是连接 MCP 服务器后可以提供给 Claude 的一些示例命令：

打印机控制

• “我的 3D 打印机当前状态是什么？”
• “给我看看打印机上的文件列表。”
• “上传这个 G-code 到我的打印机：[G-code 内容]”
• “开始打印名为 'benchy.gcode' 的文件。”
• “取消当前打印任务。”
• “将挤出机温度设置为 200°C。”
• “将热床温度设置为 60°C。”

STL 操作和打印

• “把这个 STL 文件的底座延长 2 英寸，然后发送到切片器并在我的打印机上排队。”
• “将 model.stl 的底座延长 1.5 英寸。”
• “将这个 STL 文件按 150% 统一缩放。”
• “将 model.stl 的宽度增加一倍，但保持高度不变。”
• “将这个模型绕 Z 轴旋转 90 度。”
• “将这个 STL 模型向上移动 5mm 以在其下方创建间隙。”
• “能否只修改模型的顶部部分，使其大 20%？”
• “分析这个 STL 文件并告诉我它的尺寸和详细信息。”
• “生成这个 STL 文件的可视化，让我看看它的样子。”
• “从不同角度创建我的模型的 SVG 可视化。”
• “使这个模型的底座更宽而不改变其高度。”
• “使用 PrusaSlicer 切片修改后的 STL 文件。”
• “确认 G-code 中的温度是否为挤出机 200°C 和热床 60°C。”
• “处理这个 STL 文件，将底座延长 2 英寸，切片，并开始打印，但首先要确认温度。”
• “在 Bambu 打印机上打印 ~/Downloads/my_model.3mf。”
• “使用 AMS 插槽 0 和 2 将 ~/Desktop/calibration_cube.3mf 上传到 Bambu 打印机，并关闭热床调平。”
• “取消我的 Bambu P1S 上的打印任务。”
• “我的 Bambu 耗材预设 'Generic PETG' 的设置是什么？”
• “显示我的 Bambu 过程预设。”

Bambu Lab 打印机限制

由于 Bambu Lab 打印机 API 的性质，存在一些限制：

1. 开始打印：开始打印需要 3MF 项目文件路径、gcode 文件名、打印名称和 MD5 哈希值。此服务器中的简化 API 尚未完全支持此功能。

2. 温度控制：Bambu API 不提供直接方法来设置温度。这需要自定义 G-code 命令。

3. 文件管理：文件必须上传到打印机的“gcodes”目录。

4. FTP 安全性：文件操作目前使用打印机的 FTP 服务器，可能是不安全的（纯 FTP）。

5. 参数覆盖：只有 MQTT project_file 命令支持的参数可以通过 print_3mf 工具覆盖（例如 AMS 使用、校准标志）。切片器设置（如层高或温度）不能通过此命令在打印时更改。

6. 状态更新：通过 MQTT 进行完整的实时状态监控需要进一步实现。

限制和注意事项

内存使用

• 大型 STL 文件：处理大型或复杂的 STL 文件可能会消耗大量内存。在操作过程中，整个 STL 几何体被加载到内存中。
• 多重操作：顺序运行多个 STL 操作（尤其是大文件）可能会导致内存累积，如果垃圾回收没有及时跟上。
• MCP 环境：由于这是作为 MCP 服务器运行，请注意 Claude 的 MCP 环境有内存限制。对非常大的 STL 文件进行复杂操作可能会导致内存不足问题。

STL 操作限制

• 部分修改：部分修改功能在较简单的几何体上效果最佳。复杂或非流形网格可能会产生意外结果。
• 底座扩展：底座扩展算法通过在模型下方添加新几何体来工作。对于底部复杂的模型，结果可能不完美。
• 错误处理：虽然我们增加了健壮的错误处理，但某些边缘情况下的复杂 STL 文件仍可能引起问题。

可视化限制

• SVG 表示：SVG 可视化是简化的示意图表示，不是真正的 3D 渲染。
• 复杂模型：对于非常复杂的模型，可视化可能无法准确表示所有细节。

性能考虑

• 切片操作：外部切片器进程可能会消耗大量 CPU，并且对于复杂模型可能需要相当长的时间。
• 进度报告：对于大文件，进度更新可能在某些处理阶段显得停滞。

测试建议

• 从小型 STL 文件（<10MB）开始测试功能
• 处理大文件时监控内存使用情况
• 在简单几何体上测试修改，然后再尝试复杂几何体
• 考虑在具有至少 4GB 可用 RAM 的系统上运行较大的操作

徽章

徽章	描述
	npm 上的当前包版本
	该项目