GIMP Studio MCP

Add an alpha channel to the layer if it lacks one.

Add a layer mask. mask_type: white|black|alpha|alpha-transfer| selection|copy|channel. Omit `layer` for the selected/top layer. For mask_type='channel' pass `channel` (id/name) as the source, or have a channel already selected; with neither, channel masks return supported=False (GIMP 3.0.4 create_mask(CHANNEL) needs a selected channel and exposes no source-channel parameter).

Apply any GEGL operation to a layer (destructive merge). `op` = full op name e.g. 'gegl:pixelize'. `params` = {property: value} (underscores become hyphens; color-like values auto-coerced).

Merge the layer's mask into its alpha (destructive). No-op if no mask.

Tag the image with an ICC profile WITHOUT converting pixels (assign). `icc_path` = path to a .icc/.icm file. RGB/working-space use.

Add a bleed margin (resize canvas by bleed_in on each side) and report the inner safe-area rect (inset by safe_in).

Adjust brightness and contrast. Each ranges -1.0..1.0 (0 = no change).

Flood-fill from seed point (x, y) with `color` (or current fg). mode = layer-mode name (e.g. 'normal', 'multiply').

Report availability of each font name -> {name: bool}.

Snapshot an image (a real duplicate) so you can restore() it later. Returns a numeric checkpoint_id. `image` = id/basename, or omit for active.

Binarize the ALPHA channel at `threshold` (0-1, default 0.5): pixels below it -> fully transparent (drops faint dust/noise), at/above -> fully opaque (crisp ink edges for film). RGB is untouched. NOTE: this HARDENS every soft/anti-aliased edge and drops intentional low-alpha interior detail (faint gradients / highlights) below the threshold — skip it, or lower the threshold, when the art has soft edges worth keeping.

Sample one pixel: returns {rgba:[r,g,b,a]} (0-255).

Shift color balance for a tonal range: shadows|midtones|highlights. Each channel pair is -100..100; preserve_lum keeps luminosity.

SOFT knockout: remove a color to transparency with graded alpha (destructive; gegl:color-to-alpha). color: name/#rrggbb. The colour is subtracted from every pixel that contains it, so edges and matching interior tones fade smoothly — great for feathered/anti-aliased backgrounds (e.g. a clean black knockout from #000000 at threshold ~0.15-0.20). Higher `transparency_threshold` (0-1) removes a wider band of near-target colours; `opacity_threshold` (0-1) sets where fully-opaque begins. For a CRISP, hard-edged cut (select-by-colour + delete, no fade) use `cutout_color`.

Convert pixels into the target ICC working space (RGB/working-space only). intent: perceptual|relative-colorimetric|saturation|absolute-colorimetric. bpc = black-point compensation.

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 the cut edge; `feather` softens it further. For a soft/graded knockout use `color_to_alpha`. Returns the colour used, `cleared`, `content_bbox` as `[x1,y1,x2,y2]` (or null), and canonical `layer`/`image` ids.

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 alpha had to be dropped)}.

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 auto from the region size; larger = more slack for an imprecise hint). Internally builds a trimap (shrink→foreground / grow→background / the ring between→unknown), runs matting, and REPLACES the selection with the refined matte. KNOWN LIMITATION — the hint must roughly FIT the subject's shape. Everything inside the shrunk hint is treated as definite foreground, so if the subject does NOT fill its box (an irregular shape, or several subjects with background showing between them), that interior background is KEPT and only the edge band is refined. A rectangular box works when the subject fills it; for an irregular subject give a rough OUTLINE *selection* (omit the box) instead. This is an edge REFINER, not a subject detector — for cutting a subject out of a busy scene (e.g. people in a crowd) use an external model (rembg/u²-net; not built in). A subject running to the image edge may also lose a thin strip there. On failure the incoming selection is restored and no scratch channel is left behind. Follow with `select_invert` + `cutout_color`/clear to knock out the background. Returns {bounds, band, hint, fg_core_empty, selection_empty, layer, image}.

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. Returns {placed, sheet_px, out_path}.

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 hue.) `mode='auto'` snaps the resolved colour to the nearest garment preset and inherits its technique (e.g. red -> hard, so reds in the art aren't eaten; black -> subtract, since on a black shirt black shows through); with no preset table it falls back to a luma rule (dark -> subtract / light -> hard). Override with 'hard'/'subtract' (case-insensitive). `tolerance` = match aggressiveness (default 0.15; a `shirt` preset supplies its own). `contiguous=True` (BOTH modes) removes only the border-connected region, so areas of the background colour ENCLOSED by artwork survive. Leave it off (default) when those enclosed areas are letter counters (the hole in an O) or donut holes — background that must knock out so the garment shows through. Turn it ON when they are interior ARTWORK in the garment colour (black linework on a black shirt). Colour cannot distinguish the two, so when a non-contiguous run clears enclosed regions the result reports `enclosed_bbox` + a `warning` telling you to re-run with contiguous=True if that was art. `feather` softens the cut. `defringe` (default OFF) trims a 1px halo but ERODES the art edge — enable only if you actually see a fringe. `clean` (default OFF) binarizes/denoises the alpha for film but HARDENS soft/anti-aliased edges — enable for crisp film output, leave off to preserve a clean subtract/feathered result. Returns the colour used, effective `…

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.