GIMP Agent MCP

Common adjustments without discovery. action: brightness_contrast, hue_saturation, curves, desaturate, invert, blur, sharpen, noise, pixelate. mode='append' keeps GEGL actions editable; mode='merge' bakes pixels. curves is destructive and needs params={channel:'value', points:[0,0,1,1]}. Returns the installed operation description used.

Apply a GEGL operation to a layer. mode='merge' bakes it in; mode='append' adds a non-destructive layer effect. Examples: white outline = op="gegl:dropshadow", params={"x":0,"y":0,"radius":0,"grow-radius":8,"color":"white"}; soft shadow = {"x":0,"y":6,"radius":12,"opacity":0.4}; blur = op="gegl:gaussian-blur", params={"std-dev-x":4,"std-dev-y":4}. gimp_help("filters") lists the useful ops.

Run a recipe over every file matching input_glob, writing to output_dir. Recipes must accept input_path and output_path.

Common canvas operations without PDB discovery. action: scale, crop, resize, rotate (angle 90/180/270), flip (direction horizontal/vertical), merge_visible, flatten. Operations bake pixels or layer structure and return the installed PDB description plus final image info.

Close an image without saving.

Read a document's selected layers, selection bounds and bridge colour/brush context. Optionally select layers or present a GUI document. With multiple images pass image_id; focused-image detection is unavailable, never inferred from list order.

Fill or draw without PDB discovery. action: fill_layer, fill_selection, rectangle, ellipse, rectangle_outline, ellipse_outline, line. Colours use the normal CSS/#hex convention; coordinates are image pixels. Shapes clear their temporary selection. Drawing bakes pixels and returns every installed PDB operation used.

Release a stored comparison snapshot. At most 16 may be retained per bridge; snapshots are also cleaned up when the bridge closes.

Run 1..100 edits on one image in ONE undo group. steps=[{op:'layer'|'text'|'select'|'path'|'layer_mask'|'apply_filter', params:{...}}]. Params use the corresponding tool arguments; image_id is injected. Reference an earlier result with {'$ref':'0.id'}. Check complete/error: failure stops later steps, preserves partial work, and always closes the undo group. One Ctrl+Z in GIMP reverts it; this is not automatic rollback or programmatic undo. No edits by another bridge request interleave within the batch.

Export an image; the extension chooses the format (.png .webp .jpg .tiff .bmp .gif .xcf). options are passed to the format's export procedure, e.g. {"quality": 0.85} for JPEG (0..1), {"quality": 80, "lossless": false} for WebP, {"compression": 9} for PNG. Unknown option names return the valid list.

Describe a GEGL operation's properties (names, types, ranges, defaults).

Search the GEGL operations available as filters (e.g. 'blur', 'shadow', 'levels', 'noise').

Read this first. How to work with GIMP through this server, by topic: start, filters, colours, text, masks, paths, layers, measure, recipes, compose, errors, or all.

Full structure of one image: layer tree with item ids, channels, paths, selection bounds, resolution.

Start GIMP 3 with the bridge running. mode='gui' opens the normal window; 'headless' runs gimp-console with no UI.

Layer operations. action: new (image_id, name, width, height, fill, x, y, position), set (name, visible, opacity, mode, x, y, lock), move (dx, dy), reorder (position, parent_id), duplicate, merge_down, delete, resize_to_image, scale (width, height), add_alpha, crop_to_content, info.

Edit or delete a non-destructive layer effect (ids from gimp_layer_effects). action='set' updates params/visible/opacity/blend_mode; 'delete' removes it.

List the non-destructive filters currently attached to a layer.

Layer masks. action='add' with type selection|alpha|alpha-transfer|white|black|copy; 'apply' bakes the mask in; 'remove' discards it; 'enable'/'disable' toggle it; 'show'/'hide' preview it.

List installed font names, optionally filtered by a regex.

List open images with ids, dimensions, file path, and layer count.

List tested multi-step recipes and their parameters.

Measure pixels instead of guessing from a render. kind='color' (rgba at image x,y), 'bbox' (bounding box of non-transparent pixels), 'histogram' (mean/median/std per channel), 'dominant' (top k colours). Defaults to the selected layer.

Create an RGB image with one layer. fill: 'transparent', 'white', 'black', 'foreground', 'background' or any colour.

Open an image file (PNG, JPEG, WebP, XCF, PSD, SVG, ...) and return its structure.

Vector paths. action='create' (image_id, strokes=[{type:'line'|'bezier', points:[[x,y],...], closed:bool}]; bezier points after the first are control1, control2, anchor triples), 'select' (path to selection), 'stroke' (draw it on layer_id with color and width), 'fill' (fill it on layer_id), 'delete'.

Call any PDB procedure by name with arguments keyed by name. Pass images/items as ids, colours as strings, enums by nick. Example: name="gimp-image-scale", args={"image": 3, "new-width": 800, "new-height": 600}; name="gimp-image-select-round-rectangle", args={"image": 3, "operation": "replace", "x": 10, "y": 10, "width": 200, "height": 80, "corner-radius-x": 20, "corner-radius-y": 20}. Use gimp_pdb_describe first when unsure.

Describe a PDB procedure: arguments with types, defaults and enum choices, plus return values.

Search GIMP's Procedure Database by words in the procedure name (e.g. 'image scale', 'layer text', 'file png').

AI subject cut-out. Runs a segmentation model on the layer and writes the result as an editable layer mask (mode='mask') or bakes it into the alpha channel (mode='apply'). Needs the optional segmentation extra. Models: u2net (default), isnet-general-use, u2net_human_seg, isnet-anime, silueta.

Render an image as PNG. layer_id isolates a layer; region crops. Diagnostic overlays may include grid, layers, selection and points. points=[{"x": 100, "y": 80, "label": "target"}]. Overlays affect only the returned preview.

Side-by-side render of a snapshot and the current image. panels is a comma list of before, after, diff (diff = pixel difference, black means identical).

Run Python inside GIMP. Gimp, Gegl, Gio, GLib and helpers image_by_id/item_by_id/make_color are available; the namespace persists between calls. Returns stdout plus the expression value or `result`. Pass image_id to wrap the call in one undo step.

Run a recipe by name with parameters. Recipes are Python jobs executed inside GIMP with defaults applied.

Selection in one tool. mode: rect, ellipse (x,y,width,height), color (color, threshold 0..1, layer_id), alpha (layer_id: select the layer's opaque pixels), item (item_id: path or channel), all, none, invert, grow/shrink/feather/border (amount), bounds (just report). op: replace, add, subtract, intersect. Returns the selection bounds.

Stop the bridge. quit_gimp defaults to True for headless sessions and False for the GUI (unsaved work is not prompted for).

Take a hidden snapshot of an image's current state so gimp_render_compare can show before/after later.

Check whether GIMP and the agent bridge are reachable. Returns GIMP version, mode, and open images.

Create a text layer (image_id + text) or edit one (layer_id). size in px, font by name (gimp_list_fonts), colour, justify left|center|right|fill, spacing, optional fixed box.