GIMP 3 MCP

Invert all colors in a layer (create a negative). Parameters: - image_index: Target image index (default 0) - layer_name: Layer to invert; defaults to active layer Returns status dict.

Invert the current selection (select what is not selected). Parameters: - image_index: Target image index (default 0) Returns status dict.

List brushes available to paint_stroke. Parameters: - filter: Optional regular expression matched against brush names, e.g. "Oils|Bristles" Brushes that paint well: "2. Hardness 025" to "100" (plain round), "Acrylic 01"/"03" (dry, textured), "Bristles 01" to "03" (streaky), "Oils 01" to "03" (soft blending), "Charcoal 01"/"Chalk 01" (grainy), "Pencil 02" (sketchy line), "Sponge 01" (soft texture). Returns: {brushes: [name, ...], count}

List fonts installed in GIMP. Parameters: - filter: Optional text matched against font names, case-insensitive (e.g. "sans") - limit: Maximum number of names to return (default 100). There can be thousands of fonts: if truncated is true, narrow with filter instead of assuming a font is missing. Returns: {fonts: [font_name, ...], count (returned), total (matching filter), truncated}

List all images currently open in GIMP. Index 0 is the most recently opened or created image, and indices shift when images are opened or closed; image_id stays the same for an image's lifetime. Every image_index parameter uses this order. Returns: - images: list of {index, image_id, name, width, height, color_mode, num_layers, file_path, is_dirty} - count: total number of open images

List all layers in an image with their properties. Parameters: - image_index: Target image index (default 0) Returns: {layers: [{index, name, id, visible, opacity, blend_mode, width, height, has_alpha, offsets, active}], count}. Index 0 is the top layer; active marks the layer that tools use when layer_name is omitted. blend_mode uses set_layer_properties names (e.g. "NORMAL"); offsets is [x, y].

Merge all visible layers into a single layer. Parameters: - image_index: Target image index (default 0) Returns: {layer_name, layer_id}

Grow, shrink, feather, border, or sharpen the current selection. Parameters: - operation: "grow", "shrink", "feather", "border", "sharpen" - amount: Pixel radius for grow/shrink/feather/border; ignored for sharpen - image_index: Target image index (default 0) Returns status dict.

Create a new blank canvas in GIMP and open it in a display window. Parameters: - width: Canvas width in pixels - height: Canvas height in pixels - name: Image name reported by list_images, also used for the background layer (default: "Untitled") - color_mode: "RGB" (default), "RGBA", "GRAY", "GRAYA" - fill: Background: "white" (default), "transparent", or a color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple) - resolution: DPI resolution (default: 72) Returns: - image_id: internal GIMP image ID - name: the image name - width / height: confirmed dimensions - color_mode: confirmed mode - display_opened: whether a GIMP window was opened Examples: - new_canvas(1024, 1024) — white 1024x1024 RGB canvas - new_canvas(1920, 1080, name="Background", fill="black") - new_canvas(512, 512, color_mode="RGBA", fill="transparent")

Open an image file in GIMP and create a display window. Parameters: - file_path: Absolute path to the image file to open (PNG, JPEG, TIFF, etc.) Returns: - image_id: internal GIMP image ID - width / height: image dimensions in pixels - color_mode: RGB / Grayscale / Indexed - num_layers: number of layers in the image - display_opened: whether a GIMP display window was created

Paint a batch of brush strokes, working in rounds like a painter. Paints on an open image. To start a new painting, first call new_canvas(width, height) (white by default), or open a file with open_image. Paint a few strokes (typically 3-30), look at the result (preview=True or get_state_snapshot), then paint the next batch. All strokes in one call land on one layer and form a single undo step in GIMP's own history. To be able to discard a round, paint it on a new layer (create_layer) and remove it with delete_layer. Every stroke is validated before anything is painted. Parameters: - strokes: 1-50 stroke objects. Only "points" is required: - points: [[x, y], ...] in image pixels, 1-2000 points (one point paints a dab). 3-12 points are enough for a curve. - tool: "paintbrush" (default), "pencil" (hard edge), "airbrush", "eraser", "smudge" - brush: Brush name from list_brushes (default "2. Hardness 050") - size: Brush size in pixels, 1-10000 (default 20) - color: Hex "#rrggbb", "#rgb" or "#rrggbbaa", or a basic name like "white" (default: current foreground). rgb() and other names are rejected. Ignored by eraser and smudge. - opacity: 0-100 (default 100) - hardness: 0-1 (default: the brush's own) - angle: -180 to 180 degrees (default 0); aspect_ratio: -20 to 20 (default 0) - spacing: Distance between dabs as a fraction of brush size, 0.01-50 (default: the brush's own) - pressure: "taper" (default; thin ends like a real stroke), "none" (even width), or a list of 0-1 values spread evenly along the stroke, e.g. [0.2, 1, 0.5] (paintbrush, pencil and airbrush only) - taper_affects: "size" (default) or "opacity" (ends fade instead of thinning) - smooth: true (default) turns the points into a smooth curve; false draws straight segments - mode: Blend mode, e.g. "normal" (default), "multiply", "screen", "overlay", "soft_light" - strength: 0-100 (default 50) for airbrush and smudge; applies with pressure "none" or a pressure list, not with "taper" - layer_name: Layer to paint on; defaults to the active layer - image_index: Target image index (default 0) - preview: Also return a snapshot of the whole image after painting - preview_max_size: Longest side of the preview in pixels (default 768) Returns {strokes_painted, layer, bbox, warnings}, plus the preview image when preview=True. bbox is {x, y, width, height} around the strokes; pass it to get_state_snapshot(region=...) to zoom in on what was just painted. Example: strokes=[ {"points": [[100, 400], [300, 330], [520, 380]], "brush": "Oils 01", "size": 120, "color": "#3b6e8f"}, {"points": [[140, 420], [300, 370]], "brush": "Bristles 02", "size": 40, "color": "#d9a441", "opacity": 80}, {"points": [[250, 360], [330, 350]], "tool": "smudge", "size": 50, "pressure": "none", "strength": 40} ]

Rename a layer. Parameters: - new_name: New name for the layer - old_name: Current name of the layer to rename - layer_index: Position index alternative to old_name - image_index: Target image index (default 0) Returns: {old_name, new_name}

Move a layer to a new stack position. Parameters: - new_position: Target stack index, 0 = top (same order as list_layers) - layer_name / layer_index: Identify the layer (defaults to active layer) - image_index: Target image index (default 0) Returns status dict.

Resize the image canvas without scaling the content. Parameters: - width, height: New canvas dimensions in pixels - anchor: Position of existing content — "center" (default), "top-left", "top", "top-right", "left", "right", "bottom-left", "bottom", "bottom-right" - fill: New canvas areas: "transparent" (default) or a color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple). A color is painted on a new bottom layer named "Canvas fill"; existing layers and the selection are left as they are - image_index: Target image index (default 0) Returns: {status, width, height, offset_x, offset_y, fill_layer (its name, or null)}

Drop and re-establish the connection to the GIMP MCP plugin. Use this when: - GIMP was restarted after the MCP client was already running - The socket connection dropped mid-session - check_server() shows not connected but GIMP is open Returns the new connection status (same format as check_server).

Rotate the entire image. Parameters: - angle: Rotation in degrees — 90, 180, 270 use lossless GIMP rotation; other values rotate all layers about the center with interpolation, enlarge the canvas to fit, and flatten - image_index: Target image index (default 0) Returns status dict.

Pick a color from the canvas, like a painter's eyedropper. Same as get_pixel_color, plus optional averaging over a radius. Parameters: - x, y: Image coordinates in pixels - radius: Average the color over this many pixels around the point (default 0 = one pixel) - sample_merged: true (default) samples what is visible across all layers; false samples one layer - layer_name: Layer to sample when sample_merged is false; defaults to the active layer - image_index: Target image index (default 0) Returns: {color_hex: "#rrggbb" (sRGB, usable as a paint_stroke color), alpha: 0-1}

Save the current image as a GIMP XCF file (preserves all layers and metadata). Parameters: - file_path: Absolute path for the output .xcf file - image_index: Index of the image to save (default 0 = most recently opened; see list_images) Returns: - status: "success" or "error" - file_path: confirmed output path

Scale an image to exact pixel dimensions. Parameters: - width: Target width in pixels - height: Target height in pixels - interpolation: "cubic" (default), "linear", "none" - image_index: Target image index (default 0) Returns: {status, width, height}

Scale an image to fit within a bounding box, preserving aspect ratio. Parameters: - max_width: Maximum allowed width in pixels - max_height: Maximum allowed height in pixels - interpolation: "cubic" (default), "linear", "none" - image_index: Target image index (default 0) Returns: {status, width, height} — final dimensions after scaling

Select the entire image canvas. Parameters: - image_index: Target image index (default 0) Returns status dict.

Select regions by color similarity. Parameters: - color: Target color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple) - threshold: Color similarity tolerance 0-255 (default 15) - operation: "replace" (default), "add", "subtract", "intersect" - image_index: Target image index (default 0) - layer_name: Layer to sample from; defaults to active layer Returns status dict.

Create an elliptical selection. Parameters: - x, y: Top-left corner of the bounding box - width, height: Bounding box dimensions - operation: "replace" (default), "add", "subtract", "intersect" - feather: Feather radius in pixels (default 0) - image_index: Target image index (default 0) Returns status dict.

Remove / deselect all selections. Parameters: - image_index: Target image index (default 0) Returns status dict.

Create a rectangular selection. Parameters: - x, y: Top-left corner of the selection - width, height: Dimensions of the selection - operation: "replace" (default), "add", "subtract", "intersect" - feather: Feather radius in pixels (default 0 = no feather) - image_index: Target image index (default 0) Returns status dict.

Raise a specific image's window to the front in GIMP. Works for images opened with new_canvas or open_image. GIMP 3 gives plug-ins no way to find windows opened from GIMP's own menus, so those return an error; every other tool still works on them by image_index. Parameters: - image_index: Index of the image to activate (from list_images) Returns status dict.

Set the GIMP foreground and/or background color. Parameters: - foreground: New foreground color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); omit to leave unchanged - background: New background color, same formats; omit to leave unchanged Returns: {foreground, background} confirmation dict.

Set properties on an existing layer. Parameters: - layer_name / layer_index: Identify the layer (defaults to active layer) - opacity: New opacity 0-100 (omit to leave unchanged) - blend_mode: Omit to leave unchanged, or one of NORMAL (default), MULTIPLY, SCREEN, OVERLAY, DARKEN, LIGHTEN, DODGE, BURN, HARD_LIGHT, SOFT_LIGHT, DIFFERENCE, HUE, SATURATION, COLOR, LUMINOSITY or DISSOLVE (case-insensitive; other names are rejected) - visible: True/False visibility (omit to leave unchanged) - image_index: Target image index (default 0) Returns status dict.

Sharpen a layer using unsharp mask. Parameters: - amount: Sharpening strength 0-500 (default 50.0) - radius: Blur radius for the mask in pixels (default 3.0) - threshold: Minimum difference before sharpening is applied (default 0) - image_index: Target image index (default 0) - layer_name: Layer to sharpen; defaults to active layer Returns status dict.

Disabled: always returns an error and leaves the image unchanged. On GIMP 3.2 this erased the whole layer instead of warping it, and GIMP 3.2 gives plug-ins no working warp operation. Use GIMP's Warp Transform tool by hand. Parameters: - vectors: List of warp stroke dicts, each with: - x, y : center of the warp influence (pixels) - dx, dy : push direction — negative dy = push upward - radius : influence radius in pixels (default: 40) - amount : deform strength 0–1 (default: 0.3) - image_index: Which open image to edit (default: 0) - layer_name: Target layer; omit to use the active/top layer Examples — make a character smile: warp_region(vectors=[ {"x": 215, "y": 355, "dx": 5, "dy": -8, "radius": 18, "amount": 0.45}, {"x": 295, "y": 355, "dx": -5, "dy": -8, "radius": 18, "amount": 0.45}, {"x": 255, "y": 370, "dx": 0, "dy": -4, "radius": 22, "amount": 0.30}, ]) Returns: {"warped_vectors": N}