# orcaslicer-mcp

**Let an AI assistant like Claude work with OrcaSlicer and your OrcaSlicer code.**

---

## What is this? (plain version)

Claude and other AI assistants can only *talk* by default. An **MCP server** is a
small helper program that gives them new *abilities* — like hands and eyes for a
job.

This helper gives the AI two sets of abilities:

1. **Work with your code.** Look at your OrcaSlicer code, check what changed, read
   files, search the code, and check if your online tests passed.
2. **Work with the slicer.** Slice a 3D model into a print file, then read back
   how long it will take, how much filament it uses, and how many layers it has.

So instead of you clicking around, you can just *ask*: "Slice the Julia vase and
tell me how long it takes," or "What changed in my code today?"

> **MCP** stands for *Model Context Protocol*. It's just the name for the standard
> way AI apps plug into helper programs like this one.

---

## What you need first

**Two halves — you may only want one.** The *slicing* half works for anyone who
has OrcaSlicer installed. The *code* half is only useful if you actually edit
OrcaSlicer's source code yourself. If that's not you, skip Git and GitHub CLI
below and ignore the `ORCA_FORK_DIR` setting.

These instructions use Windows paths, but this also runs on macOS and Linux —
just use the equivalent paths.

Each of these is free.

| Thing | Why you need it | Check it works |
|-------|-----------------|----------------|
| **Python 3.10 or newer** | This helper is written in Python. | Open a terminal and type `python --version` |
| **OrcaSlicer** | The slicer this helper drives. | Make sure it opens normally |
| **An AI app** | Claude Desktop or Claude Code (the thing you talk to). | — |
| **Git** | *Code half only:* downloads this helper and reads your code history. | `git --version` |
| **GitHub CLI (`gh`)** | *Code half only.* "CLI" means command-line tool — GitHub without the website. | `gh --version` |

No Git and only want slicing? Click the green **Code** button on the GitHub page,
choose **Download ZIP**, and unzip it wherever you like.

---

## How to install (step by step)

### 1. Download this helper

Open a terminal and run:

```
git clone https://github.com/Diterex/orcaslicer-mcp.git
cd orcaslicer-mcp
```

### 2. Find your Python

Do this **before** installing, so the package lands in the same Python your AI app
will use. Run:

```
where python
```

That prints one line per Python on your PC. Copy the one that looks like a real
install, for example
`C:\Users\YOU\AppData\Local\Programs\Python\Python312\python.exe`.

**Skip any line containing `WindowsApps`** — that one is a Microsoft Store
placeholder, not a real Python, and it will not work here.

If nothing prints at all, Python isn't installed. Get it from python.org and tick
**Add Python to PATH** during setup.

### 3. Install the one package it needs

Use the exact path you just copied, in quotes:

```
"C:\Users\YOU\AppData\Local\Programs\Python\Python312\python.exe" -m pip install "mcp[cli]"
```

You should see `Successfully installed mcp-...` at the end.

> Either version 1 or version 2 of that package works — this helper detects which
> one you have and adapts. You don't need to pick.

### 4. Tell your AI app about this helper

Your AI app keeps a settings file written in **JSON** — a plain-text format where
every quote, comma, and bracket has to be exactly right. One missing comma and the
app ignores the whole file with no error message, so copy carefully.

**Where the file lives:**

- **Claude Desktop (Windows):** press `Win+R`, paste
  `%APPDATA%\Claude\claude_desktop_config.json`, press Enter. If Windows can't find
  it, the file doesn't exist yet — open the `%APPDATA%\Claude` folder and create an
  empty text file with exactly that name.
- **Claude Code:** `C:\Users\YOU\.claude.json` in your user folder.

**Easiest option (Claude Code only) — skip the file entirely.** Run this with your
two real paths and it edits the settings for you:

```
claude mcp add --scope user orcaslicer-mcp -- "C:\Path\To\python.exe" "C:\Path\To\orcaslicer-mcp\server.py"
```

**Editing by hand?** The whole file should look like this. If yours already has an
`mcpServers` section with other helpers in it, add just the `"orcaslicer-mcp"`
block and put a comma after the block before it.

```json
{
  "mcpServers": {
    "orcaslicer-mcp": {
      "type": "stdio",
      "command": "C:\\Users\\YOU\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["C:\\Users\\YOU\\orcaslicer-mcp\\server.py"],
      "env": {}
    }
  }
}
```

Three things that trip people up:

- **Use double backslashes (`\\`) in every Windows path.** In JSON a single `\`
  means "something special follows," so `C:\Users` reads as broken text. `\\` means
  one real backslash. (Forward slashes `C:/Users/...` also work.)
- **`"type": "stdio"`** just means the app starts this helper and they pass text
  back and forth. Leave it as-is.
- **`"env"`** holds extra settings. Leave it empty (`{}`) for now — see
  [Settings](#settings-you-can-change-optional) below.

### 5. Restart your AI app

Quit it completely and reopen it. On Windows, closing the window isn't enough —
right-click the Claude icon near the clock and choose **Quit**, then start it again.

---

## Did it work?

Ask your AI:

> "List your orcaslicer tools."

If it names tools like `orca_repo_info` and `orca_slice`, you're done. In Claude
Code you can also type `/mcp` to see which helpers are connected.

## If it didn't work

| What you see | What it usually means | Fix |
|---|---|---|
| No `orca_*` tools at all | The app never loaded the settings file | Check the JSON for a missing comma or bracket; fully quit and reopen the app |
| `No module named mcp` | The package went into a different Python than the one in your config | Re-run step 3 using the exact `python.exe` path from your config |
| `No module named mcp.server.fastmcp` | An old copy of this helper with a new package | Update this helper (`git pull`) — current versions support both |
| `can't open file ... server.py` | The path to `server.py` is wrong, or has single backslashes | Copy the real path and double every backslash |
| `slicer not found` | It couldn't find OrcaSlicer | Set `ORCA_SLICER_EXE` to the full path of `orca-slicer.exe` (see Settings) |
| `path is outside the folders...` when slicing your own model | Your model sits outside the folders it's allowed to open | Set `ORCA_CORPUS_DIR` to the folder your models are in (see Settings) |

Nothing here can damage your PC — a failed setup just means the AI doesn't see the
tools. Retry as often as you like.

---

## How to use it

Just talk to your AI normally. Here are things you can try:

- "What branch am I on and what's changed?"
- "Show me my last 5 commits."
- "Did my latest tests pass on GitHub?"
- "List the test models I can slice."
- "Slice that model and tell me the print time and filament weight."
- "Read the print file we just made and summarize it."
- "Slice this clay model — is it likely to slump?"

Not sure what you can slice? Ask **"what models can I slice?"** first — it lists
what's in your models folder (see `ORCA_CORPUS_DIR` under Settings).

**Where do the sliced files go?** Into `C:\Users\YOU\.orcaslicer-mcp\out`, in a new
subfolder for each run. Open them in OrcaSlicer or send them to your printer as
usual.

**Slicing takes time.** A big model can take a minute or two, and the AI will look
like it's just sitting there while it works.

**To turn it off,** delete the `orcaslicer-mcp` block from your settings file and
restart — or run `claude mcp remove orcaslicer-mcp`.

The AI picks the right ability for what you asked.

---

## Settings you can change (optional)

**Good news: it finds most things by itself.** It looks for OrcaSlicer in the usual
places and on your system PATH (the list of folders Windows searches when you type
a program's name), so you normally don't have to tell it where the slicer is.

**Two settings are worth knowing about:**

- **To slice your own models,** set `ORCA_CORPUS_DIR` to the folder your models
  live in. For safety this helper only opens models inside that folder (plus its
  own output folder), so a model sitting in `Downloads` is refused with
  *"path is outside the folders..."* until you point this at it.
- **To use the "work with your code" tools,** set `ORCA_FORK_DIR` to the folder
  holding your copy of the OrcaSlicer source code. Skip it if you only slice.

You set any of these inside the `"env"` part of the config from step 4:

| Setting | What it points to | Auto-detected? |
|---------|-------------------|----------------|
| `ORCA_FORK_DIR` | The folder with your OrcaSlicer code. | Only if you run it from inside that folder — otherwise set it. |
| `ORCA_SLICER_EXE` | The full path to `orca-slicer.exe`. | Yes (checks PATH + normal install spots). |
| `ORCA_CORPUS_DIR` | The folder holding the models you want to slice. **Set this to slice your own files.** | Defaults to the source code's `resources/profiles` folder, which holds printer settings rather than models — so leaving it unset usually means "no models found." |
| `ORCA_OUTPUT_DIR` | Where sliced files are saved. | Yes (`~/.orcaslicer-mcp/out`). |
| `ORCA_INTEGRATION_BRANCH` | The branch your work merges into. | Defaults to `main`. |

Example (inside `"env": { ... }`):

```json
"env": {
  "ORCA_FORK_DIR": "C:\\Users\\YOU\\code\\OrcaSlicer",
  "ORCA_SLICER_EXE": "D:\\Programs\\OrcaSlicer\\orca-slicer.exe"
}
```

---

## Is it safe?

Yes, by design. A few of these abilities don't just look — they change things, like
sending your code to GitHub. None of those ever run by themselves.

First, the AI shows you exactly what it plans to do — and stops there. Nothing
actually runs until you say yes (the AI has to run the tool a second time with your
go-ahead attached). So it can't quietly push your code or open a request without you
agreeing.

Also good to know: this helper runs on **your** computer with **your** permissions,
the same as any program you start. Only install helpers you trust.

A few things it does to stay safe:

- **Stays in bounds.** It can only touch three folders: your OrcaSlicer folder, your
  models folder, and its own output folder. Everything else on your PC is off
  limits — which is also why you have to tell it where your models are before it
  will open them.
- **Your text stays text.** If you type something odd into a branch name or search
  box, it's treated as plain text, never as a secret extra instruction to run.
- **Point it at code you trust.** For the code tools, set `ORCA_FORK_DIR` to your
  own OrcaSlicer folder rather than running it inside a folder you downloaded from
  someone else.

---

## The full list of abilities (tools)

**Work with your code**

These use **Git**, the tool programmers use to track changes. A quick primer: a
**branch** is a separate line of work; a **commit** is a saved snapshot of your
changes; **upstream** is the original OrcaSlicer project your copy came from; and a
**pull request (PR)** is asking that original project to accept your changes.

| Tool | What it does |
|------|--------------|
| `orca_repo_info` | Shows your branch, remotes, and how far ahead/behind you are. |
| `orca_git_status` | Shows what's changed right now. |
| `orca_git_diff` | Shows the exact line changes. |
| `orca_git_log` | Shows recent commits. |
| `orca_branches` | Lists all branches. |
| `orca_checkout` | Switches to (or makes) a branch. |
| `orca_fetch_upstream` | Gets updates from the original OrcaSlicer project. |
| `orca_search_code` | Searches your code for a word or pattern. |
| `orca_read_file` | Reads part of a file. |
| `orca_gh_pr` | Lists, views, or (with your OK) opens pull requests. |
| `orca_gh_issue` | Lists, views, or (with your OK) opens issues. |
| `orca_ci_status` | Checks if your online tests passed. |
| `orca_commit` | Saves a commit (only with your OK). |
| `orca_push` | Sends commits to GitHub (only with your OK). |

**Work with the slicer**

| Tool | What it does |
|------|--------------|
| `orca_list_profiles` | Lists your printer profiles and test models. |
| `orca_slice` | Slices a model into a print file, in a new folder each run so nothing gets overwritten. Also shows the clay report if there is one. |
| `orca_analyze_gcode` | Reads a print file: time, filament, layers, cost. |
| `orca_read_analysis` | Re-reads the clay report from an earlier slice — the short summary, or every detail. |

### Clay printing checks (LDM)

**LDM** stands for *Liquid Deposition Modeling* — printing with a paste like clay
pushed through a nozzle, instead of melted plastic. Clay behaves differently: it can
slump, tear, or collapse under its own weight, and you usually only find out after
wasting an hour and a syringe of material.

The CeramicaSlicer version of OrcaSlicer checks your sliced file for those risks and
writes down what it found. This helper reads that report back to you, so you can ask
"is this print likely to slump?" *before* you start it.

When you slice a model that has clay mode turned on, you get **two** files instead
of one:

- `plate_1.gcode` — the print file itself. **G-code** is the plain-text list of
  moves your printer follows, line by line.
- `plate_1.gcode.ldm-analysis.json` — a small companion report sitting right next to
  it, listing the risky spots.

You don't have to open either one. When you ask the AI to slice something, it reads
the report and tells you the headline: an overall risk level, where the risk is
concentrated, and any specific warnings. To look at an older print's report later,
just ask — that's the `orca_read_analysis` tool.

#### Two things must both be true, or you get no report

**1. You need the CeramicaSlicer version of OrcaSlicer.**
A **fork** is a copy of a project with someone's own changes added. The clay checks
live in the CeramicaSlicer fork, not in the OrcaSlicer you download from the
official site. On the regular public OrcaSlicer your model slices perfectly fine —
you just get no clay report, because that version doesn't know how to write one.
This helper looks inside your fork's `build` folder for `orca-slicer.exe` and uses
it automatically; if your copy lives elsewhere, point at it with `ORCA_SLICER_EXE`.

**2. Clay mode must be switched on inside the model file.**
This is a setting saved *in the 3MF file*, not something this helper turns on. A
model with clay mode off slices normally and produces no clay report — that's
correct behavior, not a bug. Worth knowing: the case-study files in
`CeramicaSlicer/corpus/*.3mf` all have clay mode **off**, so they never produce a
report. The ready-made clay-on test models are in your fork under
`tests/data/clay_corpus/`, with names ending in `_clay.3mf`.

**Sliced something and got no report?** The tool tells you which of these two is
missing — check its `analysis_absent_reason` before assuming anything is broken.

---

## Works alongside OrcaSlicer's built-in helper

OrcaSlicer is adding its *own* built-in MCP helper
([PR #12667](https://github.com/OrcaSlicer/OrcaSlicer/pull/12667)) that controls the
app while it's open — screenshots, the 3D view, live settings. That one and this one
work well together:

- **This helper** works with your **code** and can slice **without opening the app**.
- **The built-in one** controls the **open app** (screenshots and the 3D view).

You can turn on both.

---

## License

MIT — free to use, change, and share. See [LICENSE](LICENSE).