GIMP Studio MCP

Create a new transparent RGBA layer (default sized to the image) and insert it at `position` (0=top) under optional `parent` group.

Create a text layer. font=name (else context font); size in px; color by name/#hex/(r,g,b); justify=left|right|center|fill; x/y = position offsets.

Apply a spline curve. `points` = flat [x0,y0,x1,y1,...] control points in 0.0-1.0, in LINEAR light like levels (not the sRGB values color_at reports). channel: value|red|green|blue|alpha.

HARD knockout: select a colour and DELETE it to transparency — the crisp, predictable cutout (the tool form of by-hand 'add alpha -> select by colour -> delete'). Auto-adds alpha. WYSIWYG: no auto-mode, no defringe, no alpha-clean. Colour to remove: explicit `color` (name/#hex/rgb) OR a `sample_xy=[x,y]` eyedropper (one is required). `threshold` (0-1, default 0.15) = colour-match tolerance. `contiguous=True` removes only the edge-connected region (keeps interior areas that reuse the colour); seeds from `sample_xy` if given, else the nearest-matching corner. `antialias` (default on) smooths th…

Remove a layer from the image. `layer` = id/name, or omit for active.

Convert to grayscale values in place. mode: luminance|luma|lightness| average|value.

Introspect a GEGL op: categories, description, and its properties.

Reduce edge color spill left over from a knockout (best-effort approximation; flag if results are off).

Add a drop shadow to a layer (gegl:dropshadow). x/y = offset, blur = shadow radius, grow = shadow expansion, color = name/'#rrggbb'/(r,g,b). NOTE: gegl:dropshadow ENLARGES the target layer and shifts its offsets so the soft shadow has room to render (verified on GIMP 3.0.4: a 64x48 layer at (0,0) became 116x100 at (-20,-20)). The layer may therefore extend beyond the canvas; flatten or crop afterward if you need it clipped.

Duplicate a layer; the copy is inserted just above the original. `layer` = id/name, or omit for the active layer.

Pull the art's effective alpha edge inward by `pixels` (trims a thin rim — useful before underbase or to remove fringing).

Grow (dilate) the art's alpha edge outward by `pixels`, fattening the artwork and carrying the edge colour into the grown ring (morphological alpha dilate via gegl:median-blur).

Export a transparent, print-ready PNG. PRESERVES ALPHA — merges visible layers WITHOUT flattening (flattening would drop alpha and ruin the DTF transfer). DPI: if `dpi` is given the file is tagged at it; if OMITTED the file inherits the image's CURRENT resolution (e.g. whatever `print_geometry` set). This only writes the DPI tag — it never resamples pixels, so set the physical print size with `print_geometry` FIRST, then export. Works on a duplicate (source untouched); returns the saved path and the DPI tag written.

Export an image to a file (format by extension: png/jpg/tiff/webp/...). Works on a COPY — the source image is never modified. ALPHA-SAFE: transparency is PRESERVED by default for formats that support it (png/tiff/webp/tga/gif) and only flattened for formats that can't hold alpha (jpg/bmp) — so a transparent cutout isn't silently ruined. `flatten=True` forces a flattened opaque export; `flatten=False` forces keep-alpha (merge visible, no flatten). For DTF PNGs prefer `export_dtf_png` (also tags DPI). Returns {saved, format, flattened, alpha (kept in the file?), had_alpha, warning (set when alp…

Fill the whole drawable. fill_type: foreground|background|white| transparent|pattern. `layer`/`image` optional (default active).

Flatten the image to a single layer. Destructive.

Edge-aware SUBJECT selection via SIOX/matting (gimp-drawable-foreground-extract). Refines a ROUGH hint into a clean foreground selection — good for hair/soft/complex edges and backgrounds that AREN'T a flat colour (where cutout_color / select_by_color fail). It is SEMI-automatic: it needs a rough hint and does NOT auto-detect the subject. Rough hint: pass a bounding box `x, y, w, h` roughly around the subject, OR make a rough selection first and omit the box. `band` = px the hint is grown / shrunk to form the 'unknown' boundary ring the matting solves (so the ring is ~2*band wide; default aut…

Contiguous color (magic-wand) selection seeded at x,y within threshold (0..1). op: replace|add|subtract|intersect.

Lay out multiple design files on a print sheet via a left-to-right / top-to-bottom shelf packer (gutter between items), growing height as needed, then export a transparent PNG. A design wider than the sheet's printable width is skipped with a warning; with `rotate=True`, a design that fits when turned 90 degrees is rotated instead. If no design can be placed, nothing is saved and the call returns ok=false with each file's reason. Returns {placed, skipped, sheet_px, out_path, image}.

Gaussian blur a layer (gegl:gaussian-blur). std_dev_x/y in pixels.

THE vision tool: render a scaled/cropped/composited COPY and return it as a VIEWABLE image (an MCP image block you can actually see) plus size metadata. region=[x,y,w,h] crops first; background (name/hex) flattens over an opaque colour (else alpha is kept); the longest side is scaled to <= max_dim (clamped 1..4096). If the encoded image would exceed max_bytes (~4 MB default) it is auto-downscaled to fit your context. Pass save_to=<abs path> to write the render to disk and get the path back instead of an inline image — use this for previews too large to view inline.

Metadata for an OPEN image: pixel width/height, resolution [x_dpi, y_dpi], base type, precision, file path, dirty flag, and per-layer info (size, opacity, visible, has_alpha). `image` = id/basename, or omit for the active image. To inspect a file ON DISK (e.g. verify an export's pixels / DPI), open_image it first, then call this on the returned id.

Read the image's embedded ICC profile label (None = built-in sRGB). `image` = id/basename, or omit for the active image.

Raw escape hatch: run Python inside GIMP. Returns the structured envelope {ok, result, stdout, warnings, error}; stdout is preserved even on error. Set a top-level `_result` for structured output. The persistent namespace has Gimp/Gegl/Gio/GLib/GObject/Babl, `pdb`, `find_image(spec)`, and `compat` (color/read_pixel/color_to_alpha/...). Runs arbitrary host code by design (same trust boundary as the local user); set GIMP_MCP_NO_EXEC=1 to skip registering this tool. See SECURITY.md.

Draw a gradient from (x1,y1) to (x2,y2). `gradient` = named gradient (else fg->bg). gradient_type: linear|bilinear|radial|conical-symmetric|...

Move an existing layer into a layer group at `position` (0=top).

Create an empty layer group, inserted at `position` (0=top) under optional `parent`.

Dissolve a layer group: lift its children to the group's parent (in order) and remove the empty group. Destructive to the group structure.

Apply a newsprint halftone screen. PREVIEW/APPROXIMATION ONLY — this is a visual halftone, NOT registration-accurate channel film separations.

Channel statistics (value|red|green|blue|alpha|luminance). space='perceptual' (default) computes the stats from the drawable's own pixels in the same 0-255 sRGB values as color_at/get_bitmap, returning mean, std_dev, median, min, max (all 0-255) plus pixels/count. space='gimp' returns GIMP's native PDB histogram (mean/std_dev/median/percentile, no min/max). Very large drawables are point-sampled at reduced resolution (min/max are from the sample, flagged by `sampled`).

Adjust hue/lightness/saturation. range: all|red|yellow|green|cyan|blue| magenta. hue -180..180, lightness/saturation -100..100, overlap 0..100.

Invert colors. linear=True inverts in linear light, else perceptual.

One-click DTF background / shirt-colour knockout. Auto-adds an alpha channel if the source is flat (no need to call add_alpha first). For a dead-simple crisp cutout of ONE flat colour, prefer `cutout_color` (hard) or `color_to_alpha` (soft) — this tool adds garment-aware auto-technique + presets on top. Colour to remove, by priority: explicit `color` (name/#hex) > `shirt=` garment preset (see list_shirt_presets) > `sample_xy=[x,y]` eyedropper > AUTO-DETECT from the image edges. (A `shirt=` preset still supplies the technique + tolerance defaults even when an explicit `color` overrides its hu…

Load an image file as a new layer in the image and insert it (top by default). Optional `name`/`parent`/`position`.

Adjust levels on a drawable. channel: value|red|green|blue|alpha. Inputs/outputs are 0.0-1.0 floats in LINEAR light, not the 0-255 sRGB values color_at reports: a pixel color_at reads as 200 sits at about 0.58 here. gamma is the midtone exponent.

List brush names, optionally filtered by substring.

List live checkpoints: id, snapshot image_id, and whether it's still valid.

List installed font names, optionally filtered by substring.

List available GEGL operation names, optionally filtered by substring.

List gradient names, optionally filtered by substring.

List open images: id, name (basename), width, height, dirty flag.

List palette names, optionally filtered by substring.

List pattern names, optionally filtered by substring.

List PDB procedure names, optionally filtered by substring.

NOT SUPPORTED: the libgimp API cannot enumerate installed ICC profiles — this ALWAYS fails. Returns ok=false with {supported: false, note}. Pass explicit .icc paths instead; get_profile reads an image's own profile.

List the built-in garment / shirt-colour presets for knockout_background(shirt=...) — name, display, hex, technique, tolerance.

Lock (or unlock) the layer's alpha channel against painting.

Map luminance to transparency per-pixel (destructive): default makes dark pixels transparent and bright pixels opaque (white-art-on-black); invert=True makes bright pixels transparent (knock out white/highlights). Computed directly over the layer buffer (no dedicated GEGL op exists in GIMP 3.0.4).

Merge a layer down into the one below it (EXPAND_AS_NECESSARY). Destructive. Returns the resulting merged layer.

Move a layer to absolute canvas offsets (x, y).

Create a new RGBA image. fill: white|transparent|background|foreground. Returns the new image id + size.

Auto-stretch tones to fill the full 0-255 range (like Colors > Auto > Stretch Contrast). keep_colors=False (default) stretches each channel independently — maximum contrast, but may shift colour balance; keep_colors=True stretches all channels uniformly to preserve hue (gegl:stretch-contrast).

Roll a layer's PIXEL CONTENT by (dx, dy) — distinct from offset_layer, which repositions the layer on the canvas. wrap=True wraps edges around (use it to seam-check a tileable texture); wrap=False fills the vacated strip per fill: transparent|color (color uses the `color` name/hex, default clear).

Offset a layer by a relative delta (dx, dy) from its current position.

Open an image file (any format GIMP loads). Returns new image id + size.

Add an outline beneath a text layer: alpha->selection, grow by `radius`, fill onto a new layer in `color`. Destructive (adds a layer).

Soft paintbrush stroke. points = flat [x1,y1,x2,y2,...]. Optional `brush` name + `size`; uses `color` or current fg.

Hard-edged pencil stroke. points = flat [x1,y1,x2,y2,...]. Uses `color` or current fg.

Reduce each channel to `levels` discrete tones (2..255).

Set print resolution (dpi) and/or scale to a physical size in inches. Pass width_in and/or height_in to scale (aspect preserved if one given). Reports current inches @ dpi and warns on upscaling.

Structured 2D grid of [r,g,b,a] pixels for a rectangle. Capped at w*h<=4096 (raises if larger — use get_bitmap for big areas).

Redo the last undone operation — only if GIMP exposes scriptable redo, which GIMP 3.x does NOT, so this returns ok=false with {supported: false} and redoes nothing. Use checkpoint()/restore() for reliable rollback.

Discard the layer's mask without applying it (destructive).

Rename a layer.

Move a layer to absolute `position` (0=top) within its parent, or into a different `parent` group when given.

Reset the persistent namespace. scope='soft' (default): clear user-defined vars and re-seed the baseline; the canvas/open images are untouched. scope='scratch' (guarded HARD reset): soft + delete only bridge-created scratch images (checkpoint snapshots tagged in `_gimpmcp_scratch`); never touches user-opened or agent working images.

Roll an image back to a checkpoint by rebuilding its layer stack from the snapshot. The checkpoint stays usable. `image` = which image to restore into.

Wrap-offset a layer's content by half its size so a tileable texture's seams land in the middle for inspection (pair with get_bitmap). axis: both|x|y. Destructive — undo to revert (re-running the same axis restores only when that dimension is even; for odd sizes floor(w/2) applied twice lands 1px off).

Select the entire image canvas.

Replace the selection with a border band `radius` pixels wide.

Select all pixels matching a color (name/#rrggbb/(r,g,b[,a])) within threshold (0..1). op: replace|add|subtract|intersect.

Elliptical selection inscribed in the x,y,w,h box. op: replace|add|subtract|intersect.

Feather (soften) the selection edge by `radius` pixels.

Select from a layer's alpha (opaque pixels). layer = id/name or omit for the active drawable. op: replace|add|subtract|intersect.

Select the region enclosed by a path. path = id/name or omit for the active path. op: replace|add|subtract|intersect. If the image has no paths and none is named, returns {"supported": false} (nothing to do) rather than erroring.

Grow the selection outward by `steps` pixels.

Invert the current selection.

Clear the selection (select nothing).

Rectangular selection. op: replace|add|subtract|intersect. Returns selection bounds.

Shrink the selection inward by `steps` pixels.

Save the current selection to a new channel. Returns the channel id.

Set the active image by integer id or basename string. Tools that take `image` act on the active image when it is omitted: the image last chosen here, opened or created, while it stays open; otherwise GIMP's first open image. A checkpoint copy is never the active image.

Set the background color. color = name|'#rrggbb'|(r,g,b[,a]).

Set a layer's blend mode (NORMAL, MULTIPLY, SCREEN, OVERLAY, ...). Case/sep insensitive; unknown names fall back to NORMAL.

Set the active paint brush by name (e.g. '2. Hardness 050').

Set the foreground color. color = name|'#rrggbb'|(r,g,b[,a]).

Set a layer's opacity (0-100 float).

Set the paint/context opacity (0-100).

Mutate any subset of an existing text layer's properties (omitted args are left unchanged). `layer` = id/name of a text layer.

Show/hide a layer.

NOT SUPPORTED: soft-proofing is a VIEW-only display simulation in GIMP 3.x, not a scriptable pixel operation — this ALWAYS fails. Returns ok=false with {supported: false, note}; no pixels are changed. Use convert_profile to bake the conversion instead.

GIMP/bridge health: GIMP version, bridge version, mode, open-image count, and the names seeded into the persistent namespace. `warnings` reports a bridge in GIMP older than this package expects, and any timeout setting that is not a usable number of seconds.

Stroke the active selection's outline with `color`/`line_width` (current fg/line width if omitted).

Best-effort font-substitution report: whether `old` is missing and `new` is present (does not mutate global GIMP config).

Black/white threshold: pixels in [low, high] -> white, else black. low/high are 0.0-1.0 on the same sRGB scale as color_at (divide its 0-255 values by 255). channel: value|red|green|blue|alpha.

Binarize the alpha channel at `value` (0..1) for a clean print edge (destructive).

Convert the image to GRAYSCALE mode (destructive).

Convert the image to RGB mode (destructive).

Autocrop the image to the artwork's alpha bounding box, plus optional padding (px). Removes empty transparent margins.

Undo the last operation — only if GIMP exposes scriptable undo, which GIMP 3.x does NOT (undo is interactive), so this returns ok=false with {supported: false} and rolls nothing back. Use checkpoint()/restore().

Begin an undo group on an image: subsequent edits collapse into one undo step. Pair with undo_group_end. `image` = id/basename, or omit for active.

End the undo group started by undo_group_begin on this image.

Sharpen a layer via unsharp mask (gegl:unsharp-mask). std_dev = blur radius, scale = sharpen strength.

Core DTF op: create a white-ink layer BELOW the art, filled to the art's alpha shrunk inward by `choke` px at `opacity`. Returns new layer id.