orcaslicer-mcp

OrcaSlicer MCP

让 Claude 在真实运行的 OrcaSlicer 中与你协作。它可以加载模型、排列打印板、调整设置、切片，并将结果读取为可供你分析的数据：哪个特性占用了打印时间、某项设置实际有什么作用、配置文件是否违背打印机的物理限制。每项更改都会在你眼前应用到 GUI 中，因此切片器始终由你掌控，你也能在使用过程中不断熟练。

此软件包是一个 MCP 服务，不包含任何模型。它会与 OrcaSlicer 通信，地址由你配置（默认是 localhost）；使用打印机工具时，还会向你的 3D 打印机发送只读请求。它不会向打印机发送命令，也不会向其上传任何内容。模型由你的 MCP 客户端提供。如果该客户端使用托管模型，你的对话就会像其他聊天一样发送到托管服务；你的模型、配置文件和 gcode 会留在运行切片器的机器上。将客户端指向本地模型，就不会有任何内容发送到托管服务。

功能

了解设置的含义

软件包附带离线设置参考，其中包含每个键的权威标签、工具提示、类型、范围、枚举值和默认值，因此 describe_setting、search_settings 和 compare_settings 会依据 OrcaSlicer 自身的源代码作答，而不是猜测。consult 会按主题、症状或目标，综合整理切片知识和你保存的笔记。

check_profile_physics 是一个确定性校验关卡。它会将拟议的更改叠加到实时配置上，执行流量、温度、几何形状和冷却计算，然后返回 ok、warnings 或 blocked。打印机无法达到的加速度和超过流量上限的速度，都会在用于打印前被检测出来。

设置

读取和写入实时配置中的约 800 项 OrcaSlicer 设置，可针对整个打印板，也可缩小范围：get_config、set_config、find_config_keys、set_layer_height、用于设置一组层范围的 set_height_range，以及用于设置单个对象覆盖项的 set_object_config。

在多耗材配置中，逐耗材键的读取会合并所有已加载槽位的设置，但写入时每次只能操作一个配置文件；选择配置文件会丢弃所有组中未保存的覆盖项。因此，应先编辑耗材，再编辑打印设置；docs/order-of-operations.md 说明了原因并提供了操作顺序。

配置文件

list_presets、select_preset、get_preset_config、edit_preset、save_preset、rename_preset、delete_preset。select_preset 会丢弃所有组中未保存的覆盖项，而不只是被切换组中的覆盖项；请参阅 docs/order-of-operations.md。

切片并读取结果

slice、slice_and_wait、apply_and_slice、cancel_slice、get_slice_status、get_slice_warnings、get_gcode。

get_slice_breakdown 会返回各特征的耗时、耗材用量和流量。OrcaSlicer 会在预览旁边的图例中显示相同信息，适合在屏幕上查看；此工具则将其作为数字返回，方便助手进行比较和操作：

role                    time      share   filament   mean flow
inner_wall              5m 41s    30.8%     6.43 g    16.0 mm3/s
outer_wall              3m 19s    18.0%     3.20 g    13.6 mm3/s
sparse_infill           3m 07s    17.0%     3.57 g    17.0 mm3/s
internal_solid_infill   2m 01s    11.0%     1.72 g    11.8 mm3/s
bridge                     52s     4.7%     0.26 g     4.4 mm3/s
support_interface          36s     3.2%     0.52 g    12.3 mm3/s
overhang_perimeter         28s     2.5%     0.13 g     3.7 mm3/s
internal_bridge            21s     1.9%     0.45 g    19.9 mm3/s
top_surface                19s     1.7%     0.29 g    12.5 mm3/s
brim                       12s     1.1%     0.21 g    14.7 mm3/s
bottom_surface              7s     0.7%     0.10 g    11.8 mm3/s
                        18m 24s            16.89 g

无需反复切片来查明哪个特征最耗时。它还会附带 prediction_check，并标记配置文件中请求的速度因达到流量上限而被限制的角色。

compare_slices 会在当前构建板上使用多个命名变体进行切片，并返回一份对比结果，让“层高究竟会带来多少代价？”只需问一次，而不必手动切片四次。它会在原始配置上应用每个变体，完成后恢复原配置，并返回结论以及一张已计算好所有差异的表格：

Recommended: 0.4mm - fastest with no warnings.

variant     time      filament   vs 0.4mm (baseline)
0.3mm       8h 10m    41.0 g      +1h 30m (+22%), -7.0 g (-15%)
0.4mm  *    6h 40m    48.0 g      baseline
0.5mm       5h 20m    53.4 g      -1h 20m (-20%), +5.4 g (+11%)
0.6mm       4h 35m    57.1 g      -2h 05m (-31%), +9.1 g (+19%)  thin-wall warning

只有当某个变体在耗时、耗材用量和警告方面都确实胜过其他变体时，它才会选出赢家；如果各有取舍，它会指出最快、耗材最少的变体，以及警告出现的位置，并由你决定。传入 detail=True 可查看每个变体按特征划分的明细。

模型和构建板

load_model（.stl、.obj、.3mf，以及 fork v2.3.2-mcp.3 及更高版本中的 .step 和 .stp）、list_objects（包含每个对象的世界空间边界框和 on_plate 标志）、transform_object、duplicate_object、delete_object、arrange_plate、auto_orient、check_placement、diagnose_plate、get_job_status。

多个构建板

list_plates、add_plate、select_plate、delete_plate 和 move_object_to_plate 可以像工具栏一样构建多构建板项目：每块构建板放置一个零件，并分别切片。切片、G-code、渲染和作业状态始终针对当前构建板，因此切片前请先选择构建板。list_objects 会报告每个对象所在的构建板。请勿对这类布局使用 arrange_plate：OrcaSlicer 的排列功能会再次将所有未锁定构建板上的对象排列到一起。需要 fork v2.4.2-mcp.13 或更高版本。

构建板渲染

render_plate 会返回 PNG，让助手可以直接查看，而不必根据坐标推断。看图就能立即看出旋转情况，而三个欧拉角几乎无法说明问题。七种视角包括 iso、top、front、left、right、rear 和 bottom。使用 frame="plate" 可拉远视角，查看整个热床；使用 frame="object" 可拉近查看零件。需要 fork v2.3.2-mcp.4 或更高版本。

view="editor"	view="preview"
热床上的模型。可查看朝向、与构建板的接触情况以及首层占地范围。	按特征角色着色的切片工具路径，支撑位置一目了然。

describe_plate 会以数字和每个对象一句话的形式回答相同问题，数据根据切片后的 G-code 计算得出：零件的放置状态（平放、倾斜，或落在边缘或角上；根据首层接触面积与最宽层的对比判断）、由多个区域组成的首层占地范围、悬垂挤出在各高度区间的集中位置、支撑的立足位置及其与零件的接触位置，以及接缝位于哪一侧（并与 seam_position 对照）。之所以提供此功能，是因为助手读取句子的可靠性高于读取图片。对象的副本会合并统计；这些区域仍会显示每个副本的接触范围。在一块放有三个倾斜支架副本的构建板上，返回结果如下：“bracket.stl（3 个副本）落在边缘或角上：首层接触面积占其最宽层的 5%，分布在 3 个区域，每个约 50 mm2。悬垂挤出集中在 Z 0 至 10 mm 处。支撑从 Z 0.4 延伸至 56.8 mm，立足于 3 处，并在 7 个区域与零件接触。接缝位于 +Y 侧（91%），与 seam_position=back 相符。”

实时状态和记忆

get_status 和 watch_events 会报告切片软件当前正在进行的操作。remember 会将机器、用户和项目相关信息保存为纯本地文件，供后续会话使用，文件位于 ~/.orcaslicer-mcp/notes/，可通过 ORCA_MCP_NOTES_DIR 更改位置。

打印机反馈

get_printer_status 会报告打印机当前正在进行的操作：空闲、加热、打印、暂停、完成，或因故障停止，并提供喷嘴和热床温度、任务进度和剩余时间，以及打印机用自己的措辞报告的任何问题。常见的 Klipper 消息会附带简短易懂的提示。wait_for_printer 会等待打印机完成加热、开始挤出，或完成第一层，也可以等待任务结束（完成、取消或失败）。OctoPrint 不会报告挤出状态，因此在使用 OctoPrint 时，等待 printing 意味着等待任务开始运行且加热器达到温度。如果打印机报告故障，或任务在等待目标状态之前结束（例如在加热时取消打印），它会提前返回。它可以应对短暂的网络中断：连续三次检查失败后，它会停止等待，并报告“Lost contact with the printer”以及最后一次获取的状态。list_print_history 会列出近期任务，说明每个任务如何结束、实际耗时与切片软件估算耗时的对比，以及失败任务的原因（前提是打印机控制台仍保留该信息）。check_printer_match 会将当前配置文件与打印机自身设置进行对比：喷嘴尺寸、热床尺寸、速度和加速度限制、最高温度以及固件回抽。数据不足以进行检查时，结果会显示为未知；完全无法检查时，结果会明确说明，而不会报告匹配。Klipper 的 max_accel 若低于所请求的加速度，会触发警告，因为当前版本的 Klipper 会接受 G-code 设置的更高值（M204 或 SET_VELOCITY_LIMIT），导致打印机以超过其配置限制的加速度运行。速度超过 max_velocity 时会被降低，除非 G-code 提高了该限制。

该服务会通过 OrcaSlicer 查找打印机。它会从当前打印机配置文件的连接设置中读取地址，因此只要已在 OrcaSlicer 中连接打印机，就无需进行其他设置。Klipper 打印机（Moonraker）可使用全部四个工具；OctoPrint 可使用状态查询和等待功能，但不支持等待第一层。若该地址无法从运行此服务的机器访问，请设置 ORCA_PRINTER_URL；若打印机需要密钥，请设置 ORCA_PRINTER_API_KEY；若要在结果存储中为打印机命名，请设置 ORCA_PRINTER_ID。未设置时，名称依次取自 ORCA_PRINTER_URL 的主机名（如果已设置）、打印机配置文件名称，否则为 unknown。ORCA_PRINTER_URL 可以包含用户名和密码，例如 http://user:[email protected]；其中的特殊字符需进行百分号编码，例如将 @ 编码为 %40。不会读取 OrcaSlicer 自身打印机地址中保存的用户名和密码，因此请改用 ORCA_PRINTER_URL 或 ORCA_PRINTER_API_KEY。这些工具只会读取打印机信息，不会发送 G-code、更改温度，也不会启动或停止任务。

从实际打印中学习

save_gcode 会保存上一次成功切片的 G-code，并记录模型名称、对象名称和尺寸的指纹、完整的设置快照，以及生成该 G-code 的 OrcaSlicer 时间和耗材估算值。如果设置了 PRINT_OUTCOMES_DIR，G-code 会存入该目录下的 gcode 文件夹；否则，如果这台机器上已有共享打印结果文件夹（~/projects/_shared/print-outcomes/），则存入该文件夹；如果没有，则存入 ~/.orcaslicer-mcp/（与 remember 使用同一文件夹）。切片前，recall_prints 会读取结果存储区，让助手能够说明该模型过去的实际打印情况：成功、已取消，或你给出的判定；打印失败时打印机报告的原因，以及所用设置。

save_gcode 会将每次切片记录到本地结果存储区，默认为 ~/.orcaslicer-mcp/outcomes/，除非 PRINT_OUTCOMES_DIR 指定了其他位置（如果已有 ~/projects/_shared/print-outcomes/ 文件夹，则直接使用）。list_print_history 会将 Klipper 打印机自身历史记录中的已完成任务复制到同一存储区，并按文件名与这些切片进行匹配，因此 recall_prints 无需其他软件就能从实际结果中学习。在这些记录中，duration_s 是 Moonraker 的整个任务时长，包含预热和任何暂停，因此与估算值相比会夸大超时幅度；list_print_history 会比较不包含这两项的打印时长与估算值。filament_g 是 G-code 文件自身的估算值，因为打印机报告的耗材单位是毫米，而不是克。klipper-mcp 配套项目仍可一同使用：它的记录器会在每次打印结束时写入结果，而它的 start_print 工具会上传 save_gcode 保存的文件。你手动从存储区删除的已完成打印记录，只要该任务仍在 Moonraker 的近期历史记录中，就会重新出现，但不会包含已保存的切片设置；这是因为 list_print_history 和 klipper-mcp 的记录器会再次将近期任务复制到存储区。若要彻底删除，也请从 Moonraker 的历史记录中删除该任务。这两个项目都不会主动联系你；助手会在下次调用 list_print_history 或 recall_prints 时看到新结果。

所需条件

标准版 OrcaSlicer 未附带控制 API，因此需要匹配的构建版本来完成这部分功能。

1. OrcaSlicer MCP 构建版本。 OrcaSlicer 2.3.2，内嵌本地 API，通过令牌进行身份验证，并默认绑定到 localhost。你可以从发布页面获取。如果你的平台暂时还没有可用的二进制文件，请从源代码构建 remote-api 分支。
2. 此软件包（orcaslicer-mcp）。 将 AI 客户端连接到该构建版本的 MCP 服务。

更新： 请从发布页面获取新构建版本，切勿在应用内更新。应用内更新程序提供的是标准版 OrcaSlicer，不包含控制 API。mcp.2 及更高版本会为你关闭该更新程序。较早版本如果出现“有新版本可用”的提示，请点击 跳过此版本。

快速开始

请先安装 uv，因为它提供了用于运行服务的 uvx 命令。在 macOS 和 Linux 上运行一行命令即可：curl -LsSf https://astral.sh/uv/install.sh | sh；在 Windows 的 PowerShell 中运行 irm https://astral.sh/uv/install.ps1 | iex。

1. 安装 OrcaSlicer MCP 版本，启动它，并选择打印机以完成一次性设置。全新安装可能会显示 “Bambu Network Plug-in Required” 对话框。点击 Skip for Now，因为该插件仅用于 Bambu 云打印。设置完成后，控制 API 会启动。

2. 打开 Preferences（Ctrl+P），前往 Remote API，勾选 Enable Remote API。复制该页面上显示的令牌。除非同时启用“Allow LAN access”，否则访问仅限 localhost。

3. 连接 MCP 客户端。

   Claude Desktop： 从 发布页面 下载 orcaslicer-mcp-<version>.mcpb 并打开该文件。Claude Desktop 会提示安装。之后打开扩展的设置，粘贴第 2 步中的令牌并启用扩展。

   忽略任何让你手动编辑 claude_desktop_config.json 的指南。当前版本的 Claude Desktop 会自行重写该文件并删除新增的 mcpServers 条目，因此所做的修改不会保留。该扩展不会改动此文件，并会自行找到 uvx。

   Claude Code 和其他 MCP 客户端： 将服务添加到客户端的 MCP 配置中。对于 Claude Code，这意味着添加到项目的 .mcp.json：

   {
     "mcpServers": {
       "orcaslicer": {
         "command": "uvx",
         "args": ["orcaslicer-mcp"],
         "env": {
           "ORCA_API_TOKEN": "<token from Preferences>"
         }
       }
     }
   }
   

   ORCA_API_URL 默认为 http://127.0.0.1:13130。仅在更改了端口，或 OrcaSlicer 在启用了 LAN 访问的另一台机器上运行时，才需要设置它。

   Windows 注意事项： 如果在安装 pywin32 时运行 uvx orcaslicer-mcp 报错 "The process cannot access the file because it is being used by another process"，这是因为 Windows Search 或 Defender 在安装过程中占用了刚写入的文件（uv 不会重试）。请改用会重试的基于 pip 的备用方案，并将 "command" 指向生成的 exe：

   python -m venv "$env:USERPROFILE\.venvs\orcaslicer-mcp"
   & "$env:USERPROFILE\.venvs\orcaslicer-mcp\Scripts\python" -m pip install orcaslicer-mcp
   

   然后将 "command" 设置为 C:\Users\<you>\.venvs\orcaslicer-mcp\Scripts\orcaslicer-mcp.exe，无需设置 args。之后升级时，使用相同的 pip 命令并加上 -U。

   macOS 上 Claude Desktop 以外的图形客户端注意事项： 从 Dock 启动的应用不会继承终端的 PATH，因此 "command": "uvx" 可能会静默失败。在终端中运行 which uvx，然后将输出的完整路径粘贴到 "command" 中。该路径通常是 ~/.local/bin/uvx。

4. 重启客户端并提问：“加载 benchy.stl，使用当前配置切片，并告诉我打印所需时间。”

安全

• 默认情况下，控制 API 仅绑定到 127.0.0.1。在局域网中访问需要在偏好设置中明确启用。
• 每个请求都必须携带 API 令牌。OrcaSlicer 会在首次运行时生成令牌，也可随时重新生成。
• MCP 服务作为本地 stdio 进程运行。它只连接 OrcaSlicer；使用打印机工具时，还会向 OrcaSlicer 当前打印机配置文件中指定地址（或 ORCA_PRINTER_URL）的打印机发送只读 HTTP GET 请求。它不会向打印机发送命令，也不会向其上传任何内容。无遥测。
• MCP 服务拒绝更改会运行代码或直接驱动打印机的配置键，包括 post_process、所有 *_gcode 模板、printer_model、printer_technology、filename_format，以及打印机连接设置（print_host、printhost_*、host_type、printer_agent 和 OrcaSlicer 的其他实体打印机配置键）。列表位于 src/orcaslicer_mcp/guard.py 中。持有 API 令牌的助手可能会受其读取的文本操纵，例如模型名称、G-code 或网页。由于 post_process 会在导出后运行 shell 命令，因此这些操作仍由用户在 OrcaSlicer GUI 中决定。
• 允许将配置键写回其当前值，因此恢复操作仍可正常工作。主机地址及其凭据是例外。OrcaSlicer 从不报告它们的当前值，因此任何对它们的写入都会被拒绝。edit_preset 会在选择配置预设前执行检查，因此编辑被拒绝时，你未保存的更改不会受影响。
• 若要允许 MCP 写入特定配置键，请将其列在 ORCA_MCP_ALLOW_KEYS 中，并用逗号分隔。支持通配符，例如 *_gcode。Claude Desktop 扩展将其作为一项设置提供。服务启动时会记录所有未匹配任何受保护配置键的名称，这通常意味着输入有误。
• 此检查仅覆盖 MCP 服务自身的工具。也能运行 shell 命令的助手可以读取令牌并直接调用 OrcaSlicer。OrcaSlicer MCP v2.4.2-mcp.10 及更高版本会在切片器内部应用相同规则；勾选偏好设置 → 远程 API 中的 允许编辑脚本、G-code 和连接设置 后，此规则才会停用。在这些版本中，助手需要同时满足两个条件：勾选该选项，并将配置键列在 ORCA_MCP_ALLOW_KEYS 中。
• get_preset_config 会隐藏 printhost_apikey、printhost_user 和 printhost_password。它还会隐藏 print_host 和 print_host_webui 中的 user:password@ 部分，从最后一个 @ 处截断，因此即使密码包含 /、@、?、# 或空格，也会被隐藏。路径中含有 @ 的 URL 也会丢失该 @ 之前的部分，因为这种情况看起来和密码中含有 / 一样。带有 <redacted> 占位符的值绝不会被写回。

开发

uv venv && uv pip install -e ".[dev]"
uv run pytest   # unit tests against a mock API, plus a guarded live smoke test

只有当 ORCA_API_URL 和 ORCA_API_TOKEN 指向正在运行的 OrcaSlicer MCP 版本时，实时冒烟测试才会运行；否则会跳过。

设计规范和协议说明位于 docs/ 中。

隐私政策

服务会在你配置的地址（默认是 localhost）与 OrcaSlicer 的本地 API 通信；使用打印机工具时，还会与 OrcaSlicer 打印机配置文件中的地址（或 ORCA_PRINTER_URL）所对应的 3D 打印机通信。它不会与任何其他对象通信。它没有后端，因此我们没有任何可供数据访问的服务。除了这些打印机请求之外，离开你设备的数据，就是 MCP 客户端发送给其模型的内容：对话，以及你或助手放入其中的任何设置或文件内容。该流量受其条款约束，与使用该客户端的其他任何方式产生的流量相同。使用本地模型则可完全避免数据外传。

• 数据收集： 无。服务不会收集有关你或你的使用情况的任何信息。
• 使用和存储： 模型、设置和 G-code 都保留在运行 OrcaSlicer 的计算机上。请求运行期间，它们会在内存中经过服务；服务只会将下方数据保留项中列出的内容写入磁盘。API 令牌用于验证服务与 OrcaSlicer 之间的身份，MCP 客户端会存储该令牌。若你设置了 ORCA_PRINTER_API_KEY，打印机密钥会用于验证服务与打印机之间的身份，并以相同方式存储。打印机状态、历史记录和设置会作为工具结果返回给 MCP 客户端，因此会像其他工具输出一样加入对话。Claude Desktop 会将标记为敏感信息的设置（OrcaSlicer API 令牌和打印机密钥）保存在操作系统的凭据存储中。ORCA_PRINTER_URL 中的密码会作为普通设置存储，因此如果打印机支持密钥，请优先使用 ORCA_PRINTER_API_KEY。
• 与第三方共享： 本服务不会与第三方共享数据，也没有分析功能或后端。客户端与其模型提供商之间的流量不属于本项目范围，受其各自政策约束。
• 数据保留： 写入磁盘的数据仅包括：你使用 remember 自行保存的备注，以纯文本文件形式存储在 ~/.orcaslicer-mcp/notes/ 下；save_gcode 写入的 G-code，在共享文件夹已存在时存储于 ~/projects/_shared/print-outcomes/，否则存储于 ~/.orcaslicer-mcp/；结果存储库（outcomes.db），其中包含切片记录（模型名称、对象名称和大小的指纹，以及每次切片使用的设置）和 list_print_history 从打印机复制的已完成打印结果；这些数据在共享文件夹存在时存储于该文件夹，否则存储于 ~/.orcaslicer-mcp/outcomes/；以及 ~/.orcaslicer-mcp/printer.json，它会记住上次响应的打印机地址（绝不保存密码）。PRINT_OUTCOMES_DIR 可更改 G-code 和结果存储库的位置。你可以随时读取或删除其中任何内容。删除后不会留下任何数据。
• 联系方式： 如有疑问或顾虑，请提交问题。

状态

公开发布初期，处于软启动阶段。服务拥有 500 多个单元测试，并会在真实打印任务中进行测试。发布页面提供适用于 Windows、macOS 和 Linux 的预构建 OrcaSlicer MCP 版本。欢迎提交问题和报告。

支持

本项目免费，并将一直免费。如果它为你节省了时间，而你想表达感谢，可以请我喝杯咖啡。

许可证

AGPL-3.0，与 OrcaSlicer 相同；随附设置架构源自 OrcaSlicer 的源代码。请参阅 LICENSE。