orca-mcp

An MCP server that wraps the OrcaSlicer CLI, letting any MCP compatible agent (Claude Code, Ollama, Codex, etc.) slice models, run parameter sweeps, and analyze the resulting G-code.

MCP client ──stdio──▶ orca-mcp ──subprocess──▶ orca-slicer CLI ──▶ G-code + estimates

Works on Linux, macOS, and Windows, including Flatpak and AppImage installs of OrcaSlicer.

Why

The OrcaSlicer CLI can slice headlessly, but driving it by hand means juggling profile paths and grepping G-code comments. This server turns that into structured tools an AI agent can use: "slice this model with fan speeds of 20/40/60% and tell me which layers at the shoulder transition change" becomes a two-tool-call workflow.

Requirements

• Python 3.10+
• OrcaSlicer installed (native package, AppImage, Flatpak, or Windows/macOS installer)
• Linux headless machines: xvfb-run recommended (dnf install xorg-x11-server-Xvfb / apt install xvfb) — some OrcaSlicer builds need a display context even in CLI mode. The server detects this and retries under xvfb automatically.

Install

pip install orca-mcp

# or from source:
git clone https://github.com/jeff-roche/orca-mcp
cd orca-mcp && pip install .

Configure your MCP client

Claude Desktop (claude_desktop_config.json) or Claude Code (claude mcp add):

{
  "mcpServers": {
    "orca-mcp": {
      "command": "orca-mcp"
    }
  }
}

If OrcaSlicer isn't on your PATH, point the server at it:

{
  "mcpServers": {
    "orca-mcp": {
      "command": "orca-mcp",
      "env": {
        "ORCASLICER_PATH": "/home/you/Applications/OrcaSlicer_Linux_V2.3.0.AppImage"
      }
    }
  }
}

How the slicer is located

First match wins:

1. ORCASLICER_PATH env var (any executable, including an AppImage)
2. orca-slicer / OrcaSlicer on PATH
3. Well-known locations:
   • Linux: /usr/bin, /usr/local/bin, ~/.local/bin, ~/Applications/*.AppImage
   • macOS: /Applications/OrcaSlicer.app/Contents/MacOS/OrcaSlicer
   • Windows: %ProgramFiles%\OrcaSlicer\, %LocalAppData%\Programs\OrcaSlicer\
4. Flatpak (com.orcaslicer.OrcaSlicer, with legacy io.github.softfever.OrcaSlicer as fallback)

How profiles are located

User profiles are discovered from the standard OrcaSlicer config directory (~/.config/OrcaSlicer on Linux, ~/Library/Application Support/OrcaSlicer on macOS, %APPDATA%\OrcaSlicer on Windows, plus the Flatpak sandbox path). Override with ORCASLICER_CONFIG_DIR if yours lives elsewhere.

Only user profiles are enumerated by list_profiles. Vendor/system presets still work — pass a path to an exported profile JSON instead of a name.

Tools

Tool reference

check_installation()

No arguments. Returns the resolved executable/invocation, platform, and version banner. Call this first if any other tool fails unexpectedly.

list_profiles(profile_type=None)

Returns {"count", "profiles", "note"}. Only user profiles are listed — see How profiles are located.

get_profile(name_or_path, profile_type)

Returns {"profile", "settings"} — settings is the full profile JSON, useful for finding valid process_overrides/filament_overrides keys.

get_model_info(model_path)

Runs OrcaSlicer's --info and returns bounding box, volume, and facet count.

slice_model(...)

Returns G-code path(s) plus parsed estimates ({"output_dir", "gcode_files", "profiles_used", "estimates", ...}).

parameter_sweep(...)

Slices once per value and returns one entry per value ("runs") plus a flattened "comparison" table of time/filament, so results can be diffed — e.g. by feeding each G-code path to analyze_gcode_layers.

get_slice_estimates(gcode_path)

Parses print time, filament usage, and key settings out of the G-code header comments.

analyze_gcode_layers(gcode_path, z_min=None, z_max=None, max_layers=300)

Returns per-layer Z, layer height, feature types, fan speed, and print speed range — useful for inspecting a specific region (e.g. an overhang) and comparing across sweep runs.

Overrides

slice_model accepts process_overrides and filament_overrides dicts. Keys are OrcaSlicer's internal setting names — run get_profile on your process profile to see them. The server merges overrides into a temp copy of the profile (handling Orca's string/list-of-strings value convention) and passes that to the CLI, so your saved profiles are never modified.

// example slice_model arguments
{
  "model_path": "/home/you/discs/fairway-driver-v7.stl",
  "machine_profile": "Elegoo Centauri Carbon 0.6 nozzle",
  "process_profile": "0.2mm TPU disc",
  "filament_profile": "Generic TPU",
  "process_overrides": { "wall_loops": 4, "slow_down_layer_time": 12 },
  "filament_overrides": { "fan_max_speed": [30] }
}

Example agent workflows

Basic slice + estimate:

"Slice mdoel.stl with my TPU profiles and tell me the print time and filament weight."

Parameter sweep:

"Sweep fan_max_speed over 20, 40, 60, 80 on model.stl and compare print times."

Regional G-code inspection:

"For each sweep result, analyze layers between Z=8mm and Z=12mm and tell me where fan speed and print speed diverge."

Platform notes

• Linux (native/AppImage): if running with no $DISPLAY and the slicer aborts with a GL/display error, the server retries under xvfb-run -a automatically when available.
• Linux (Flatpak): invoked via flatpak run <app-id>. Note the Flatpak sandbox can only read paths it has permission for — models under $HOME are fine by default; use flatpak override --filesystem=... for other locations.
• Windows: orca-slicer.exe (the console binary) is preferred over OrcaSlicer.exe when both exist.
• macOS: point ORCASLICER_PATH inside the app bundle if the auto-detected location doesn't match your install.

Caveats

• The CLI is a subset of the GUI: no live preview, and some calibration flows are GUI-only. Slice/estimate/export covers the automation use cases.
• CLI flags have shifted slightly across OrcaSlicer versions (e.g. --load-filaments vs --load-filament, --export-3mf availability). This server targets OrcaSlicer 2.x; open an issue with your check_installation output if a flag mismatch bites you.
• Estimates come from the G-code header, i.e. the slicer's own time model — treat them as relative comparisons between sweep runs, not stopwatch truth.

Development

pip install -e ".[dev]"    # installs pytest + ruff
pytest
ruff check .

The test suite covers G-code parsing, layer analysis, profile discovery, and override merging with synthetic fixtures — no OrcaSlicer install needed to run it. Both pytest and ruff check run in CI on every push/PR (.github/workflows/ci.yml).

License

MIT