Metadata-Version: 2.4
Name: orcaslicer-mcp
Version: 0.1.1
Summary: OrcaSlicer MCP — drive OrcaSlicer from Claude or any MCP client: load models, tune settings, slice, analyze
Project-URL: Homepage, https://github.com/maxellis/orcaslicer-mcp
Project-URL: Repository, https://github.com/maxellis/orcaslicer-mcp
Project-URL: OrcaSlicer MCP build (fork), https://github.com/maxellis/OrcaSlicer
Author: Max Ellis
License: AGPL-3.0-only
License-File: LICENSE
Keywords: 3d-printing,claude,mcp,model-context-protocol,orcaslicer,slicer
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Printing
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Requires-Dist: websockets>=12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# OrcaSlicer MCP

**Drive OrcaSlicer with AI.** OrcaSlicer MCP is an [MCP](https://modelcontextprotocol.io) server that lets Claude (Desktop or Code — or any MCP client) operate a real, running OrcaSlicer: load models, arrange the plate, tune settings, slice, and analyze the result — live, with every change visible in the GUI.

The slicer stays authoritative and on your machine. The server contains no LLM and makes no cloud calls; it talks only to OrcaSlicer on localhost (or a host you explicitly allow).

## How it works

Two pieces:

1. **The OrcaSlicer MCP build of OrcaSlicer** — OrcaSlicer 2.3.2 with an embedded local control API (token-authenticated, localhost-only by default). Get it from the [releases page](https://github.com/maxellis/OrcaSlicer/releases); if no binary is up for your platform yet, build the `remote-api` branch from source.
2. **This package (`orcaslicer-mcp`)** — the MCP server that connects your AI client to that build.

Stock OrcaSlicer does not have the control API — the MCP server requires the build above.

> ⚠️ **Don't update from inside the app.** This build is based on OrcaSlicer 2.3.2, so OrcaSlicer's own "new version available" prompt will offer to "upgrade" you — but that installs *stock* OrcaSlicer and **removes the control API**, breaking OrcaSlicer MCP. Always click **Skip this Version** (or **Cancel**) on that prompt. New MCP-enabled builds come only from the [releases page](https://github.com/maxellis/OrcaSlicer/releases).

## Quickstart

You'll need [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (it provides the `uvx` command that runs the server) — one line: `curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux, or `irm https://astral.sh/uv/install.ps1 | iex` in PowerShell on Windows.

1. Install and launch the OrcaSlicer MCP build, and complete the one-time first-run setup (pick your printer). On a fresh install OrcaSlicer may show a **"Bambu Network Plug-in Required"** dialog — click **Skip for Now**; that plug-in is only for Bambu cloud printing and isn't needed here. (The control API starts once first-run setup is finished.)
2. In OrcaSlicer: **Preferences** (Ctrl+P) **→ Remote API → Enable Remote API**, then copy the API token shown on that page. (Access is localhost-only unless you also switch on "Allow LAN access".)
3. Add the server to your MCP client config (Claude Desktop `claude_desktop_config.json`, or a project `.mcp.json` for Claude Code):

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

    `ORCA_API_URL` defaults to `http://127.0.0.1:13130` — set it only if you changed the port, or run OrcaSlicer on another machine (with LAN access enabled there).

4. Restart your client and ask: *“Load benchy.stl, slice it with the current profile, and tell me the print time.”*

> **Updating:** OrcaSlicer's built-in "new version available" prompt points at *stock* OrcaSlicer — installing that way replaces this build and removes the control API. Skip it, and get new MCP-enabled builds from the [releases page](https://github.com/maxellis/OrcaSlicer/releases) instead.

## What Claude can do with it

- **Plate & models:** `load_model`, `list_objects`, `transform_object`, `duplicate_object`, `delete_object`, `arrange_plate`, `auto_orient`, `check_placement`, `diagnose_plate`, `get_job_status`
- **Settings:** `get_config`, `set_config`, `find_config_keys`, `describe_setting`, `search_settings`, `compare_settings`, `set_layer_height`, `set_height_range`, `set_object_config` (per-object overrides)
- **Presets:** `list_presets`, `select_preset`, `get_preset_config`, `edit_preset`, `save_preset`, `rename_preset`, `delete_preset`
- **Slicing:** `slice`, `slice_and_wait`, `apply_and_slice`, `cancel_slice`, `get_slice_status`, `get_slice_warnings`, `get_slice_breakdown` (per-feature time/flow analysis), `get_gcode`
- **Live state & events:** `get_status`, `watch_events`

### Settings intelligence

- **`consult(query)`** — curated slicing knowledge plus your saved notes, composed per topic, symptom, or goal.
- **`check_profile_physics(changes?)`** — deterministic sanity gate: overlays proposed changes on the live config and runs flow/temperature/geometry/cooling math. Verdict: `ok`, `warnings`, or `blocked`.
- **`remember(note, scope)`** — persist machine/user/project facts for future sessions as plain local files in `~/.orcaslicer-mcp/notes/` (relocatable via `ORCA_MCP_NOTES_DIR`).

Plus an offline settings reference: authoritative label/tooltip/type/range/enum/default for ~800 OrcaSlicer settings, bundled with the package.

## Security

- The control API binds **127.0.0.1 only** by default; LAN access is an explicit opt-in in Preferences.
- Every request must carry the API token; OrcaSlicer generates it on first run and can regenerate it at any time.
- The MCP server is a local stdio process. No telemetry, no cloud.

## Development

```bash
uv venv && uv pip install -e ".[dev]"
uv run pytest   # unit tests (mock API) + a guarded live smoke test
```

The live smoke test is skipped unless `ORCA_API_URL` / `ORCA_API_TOKEN` point at a running OrcaSlicer MCP build.

Developer docs — protocol notes, design specs, verification results — live in [`docs/`](docs/).

## Status

Early public release (soft launch). The server is exercised by ~170 unit tests and real print workflows; prebuilt OrcaSlicer MCP builds are available for Windows, macOS, and Linux on the [releases page](https://github.com/maxellis/OrcaSlicer/releases). Issues and reports welcome.

## License

AGPL-3.0 — the same license as OrcaSlicer, from whose source the bundled settings schema is derived. See [LICENSE](LICENSE).
