Siril MCP

LLM control of a live Siril GUI session via an in-app Python bridge.

Works on macOS, Linux and Windows, with Cursor, opencode and any MCP client.

Architecture

1. Bridge (bridge/bridge.py) — started inside Siril with pyscript -async. Talks to Siril through sirilpy and listens for MCP requests.

2. MCP server (siril-mcp) — stdio MCP process; forwards tools to the bridge.

MCP client → siril-mcp (stdio) → bridge → Siril

Transport between server and bridge:

Select explicitly with SIRIL_MCP_TRANSPORT=unix|tcp. Default is unix where supported, otherwise tcp. Set the same variables on both sides (MCP server env + Siril launcher).

Related MCP server: krita6-mcp

Setup

1. Install the MCP package

cd /path/to/siril-mcp
uv sync

or with pip:

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

2. Install the Siril launcher

macOS / Linux:

./scripts/install_bridge_to_siril_scripts.sh

Windows (manual): the script above only knows macOS paths. Copy the launcher by hand:

1. Create the folder C:\Users\<you>\AppData\Roaming\siril\scripts if missing (check Siril's script path in config.1.4.ini, key script_path).

2. Create Start_MCP_Bridge.py inside it with this content (adjust the bridge path):

#version = 1.3.0
import os
import runpy

os.environ.setdefault("SIRIL_MCP_TRANSPORT", "tcp")
os.environ.setdefault("SIRIL_MCP_HOST", "127.0.0.1")
os.environ.setdefault("SIRIL_MCP_PORT", "27777")

runpy.run_path(r"E:\siril-mcp\bridge\bridge.py", run_name="__main__")

3. Start the bridge in Siril

Open Siril, wait until the log shows Python module is up-to-date and Caricamento dello script: Start_MCP_Bridge.py, then:

• Scripts menu → Start_MCP_Bridge (prefer async), or

• Siril command line: pyscript -async /path/to/siril-mcp/bridge/bridge.py

You should see in the Siril log:

[siril-mcp] connected to Siril
[siril-mcp] listening on tcp 127.0.0.1:27777

(on macOS/Linux: listening on .../bridge.sock). Keep Siril open while using the MCP.

4. Register the MCP server

opencode (C:\Users\<you>\.config\opencode\opencode.json or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "siril": {
      "type": "local",
      "command": ["uv", "--directory", "E:\\siril-mcp", "run", "siril-mcp"],
      "enabled": true,
      "environment": {
        "SIRIL_MCP_TRANSPORT": "tcp",
        "SIRIL_MCP_HOST": "127.0.0.1",
        "SIRIL_MCP_PORT": "27777"
      }
    }
  }
}

On macOS/Linux the environment block can be omitted (Unix socket is the default).

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "siril": {
      "command": "/path/to/siril-mcp/.venv/bin/siril-mcp",
      "args": [],
      "env": {
        "SIRIL_MCP_TRANSPORT": "tcp",
        "SIRIL_MCP_HOST": "127.0.0.1",
        "SIRIL_MCP_PORT": "27777"
      }
    }
  }
}

Restart the MCP client after editing. Verify with opencode mcp list (expect siril ✓ connected) or by calling siril_ping.

Optional: StarNet

If you plan to use StarNet for star removal, install it via Siril's usual StarNet setup. This stack does not install or configure StarNet; once it is available to Siril, scriptable StarNet commands work like any other command through the bridge.

Tools

If the bridge is down, tools fail with an explicit start hint (they do not fall back to browsing the filesystem).

Batch stacking without the bridge

The bridge is for interactive work on the live GUI session. For heavy batch jobs (calibrate / register / stack of many frames) prefer siril-cli with an .ssf script — same engine, headless, reproducible:

siril-cli -d /path/to/work -s stack_lights_darks.ssf

Example (lights + darks only, OSC camera, Siril 1.4):

requires 1.3.0
cd darks
convert dark -out=../process
cd ../process
stack dark rej 3 3 -nonorm -out=../masters/dark_stacked
cd ..
cd lights
convert light -out=../process
cd ../process
calibrate light -dark=../masters/dark_stacked -cfa -equalize_cfa -debayer -cc=dark
register pp_light
stack r_pp_light rej 3 3 -norm=addscale -output_norm -rgb_equal -32b -out=result

This is the reference OSC_Preprocessing.ssf workflow minus flats/biases; see the full script in Siril's script collection for the 4-frame variant.

Bridge limitations (what you don't get yet)

This stack only reaches what scripts / sirilpy already expose. GUI-only or poorly scripted Siril features are out of scope for the bridge approach, including:

• Display / STF / visu state matching exactly what the user sees in the viewport

• Inspector-style diagnostics

• Curves, remixer, and compositing UI hooks (unless a documented command equivalent exists)

• Reliable sequence / load_seq context and Python-style metadata that today only exists on GUI-only paths

• True canvas screenshots (overlays, zoom, annotations) vs an autostretched gfit preview

• Attaching to Siril without manually starting the bridge (pyscript -async)

• Headless siril-cli -p as the primary control path (optional later; not what this bridge is)

Canonical test queries

1. Ping Siril and tell me if an image is loaded, its size, filename, and selection.

2. Show a preview of the current image (max 1024px) and describe it.

3. List stretch-related Siril commands.

Troubleshooting

• Bridge not running: start pyscript -async again; check bridge.status.json under the support dir.

• Windows AF_UNIX error: fixed by the TCP fallback — make sure both the launcher and the MCP server env use SIRIL_MCP_TRANSPORT=tcp and the Siril log shows listening on tcp ....

• Port already in use: another bridge is running, or set another port via SIRIL_MCP_PORT on both sides.

• Launcher missing from Scripts menu: check Siril's script_path in the config and restart Siril after copying Start_MCP_Bridge.py.

• Socket permissions (Unix): socket is created mode 0600 under Application Support.

• First Siril run: wait until Siril finishes Python venv setup before starting the bridge.

• Nested pyscript: siril_run_script with kind=py runs sync pyscript; prefer siril_run_command for simple ops.

License

GPL-3.0-or-later — same as Siril.