Check whether the GIMP MCP plugin socket is reachable and responding.

Returns a status dict:

• connected: bool

• host / port: where it tried

• gimp_version: if connected successfully

• error: description if not connected

Use this before any other operation to verify the GIMP plugin is running. If not connected, open GIMP and run Tools > Start MCP Server.

Drop and re-establish the connection to the GIMP MCP plugin.

Use this when:

• GIMP was restarted after Claude Code 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).

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: Layer/image name (default: "Untitled")

• color_mode: "RGB" (default), "RGBA", "GRAY", "GRAYA"

• fill: Fill color for the background layer. Any CSS color name or hex string: "white" (default), "black", "transparent", "#FF5733", "rgb(100,200,50)", etc.

• resolution: DPI resolution (default: 72)

Returns:

• image_id: internal GIMP image ID

• 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")

Get the current open image in GIMP as an Image object with optional scaling and region selection.

No size restrictions — pass any max_width/max_height you need. For large images, omit max_width/max_height to get the full resolution.

Supports two main use cases:

1. Full image with optional scaling (pass max_width/max_height)

2. Region extraction with optional scaling (pass region dict)

Parameters:

• max_width, max_height: Target dimensions for scaling (aspect-ratio preserved). Omit for full resolution.

• region: Dictionary with keys:

  • origin_x, origin_y: Top-left corner of region to extract

  • width, height: Dimensions of region to extract

  • max_width, max_height: Optional scaling for the extracted region

Examples:

• Full image at full res: get_image_bitmap()

• Full image scaled: get_image_bitmap(max_width=2048, max_height=2048)

• Region: get_image_bitmap(region={"origin_x": 0, "origin_y": 0, "width": 512, "height": 512})

Returns:

• Image object containing PNG data in MCP-compliant format

• Includes width, height, and base64-encoded image data

The returned Image object automatically handles base64 encoding and MIME types according to the Model Context Protocol specification.

Raises:

• RuntimeError if no image is open, region is invalid, or export fails

Get metadata about the current open image in GIMP without the bitmap data.

Returns detailed information about the currently active image including:

• Image dimensions (width, height)

• Color mode and base type

• Number of layers and channels

• File information if available

• Layer structure and properties

This is much faster than get_image_bitmap() since it doesn't export the actual image data. Perfect for when you only need to know image properties for decision making.

Returns:

• Dictionary containing comprehensive image metadata

• Raises exception if no images are open

Get comprehensive information about the GIMP installation and environment.

Returns detailed information about GIMP that AI assistants need to understand the current environment, including:

• GIMP version and build information

• Installation paths and directories

• Available plugins and procedures

• System configuration

• Runtime environment details

This information helps AI assistants provide better support and troubleshooting by understanding the specific GIMP setup they're working with.

Returns:

• Dictionary containing comprehensive GIMP environment information

• Raises exception if GIMP connection fails

Return a live visual snapshot of the current image state — no file save needed.

AI agents call this to get immediate visual feedback after any edit operation, letting them verify results and decide next steps without saving to disk.

Parameters:

• image_index: Which open image to snapshot (default: 0 = most recent)

• max_size: Maximum width/height of the returned preview in pixels (default: 512)

• region: Optional dict {x, y, width, height} to zoom into a specific area e.g. {"x": 200, "y": 300, "width": 100, "height": 80} for mouth area

• label: Optional annotation label (logged but not drawn — for agent bookkeeping)

Returns:

• PNG image of the current GIMP canvas state (with alpha if present)

Typical agent workflow: 1. open_image / new_canvas 2. 3. get_state_snapshot() ← see result, decide next step 4. 5. get_state_snapshot(region={"x":200,"y":300,"width":100,"height":80}) 6. export_image when satisfied

Get the current GIMP context state (colors, brush, settings).

IMPORTANT: Context state can be changed by the user in GIMP UI at any time. Check context state before operations that depend on specific settings.

Returns information about:

• Foreground and background colors (RGB/RGBA values)

• Current brush and its properties

• Opacity setting (0-100%)

• Paint/blend mode

• Feather state and radius

• Antialiasing state

Use cases:

• Verify colors before drawing operations

• Check if feathering is enabled (avoid unwanted blurry edges)

• Ensure correct opacity and blend mode

• Detect if user changed settings in GIMP UI

Returns:

• Dictionary containing current context state

• Raises exception if unable to get context state

Call GIMP 3.2 API methods through PyGObject console.

GIMP MCP Protocol:

• Use api_path="exec" to execute Python code in GIMP

• args[0] should be "pyGObject-console" for executing commands

• args[1] should be array of Python code strings to execute

• Commands execute in persistent context - imports and variables persist

• Always call Gimp.displays_flush() after drawing operations

For image operations, use get_image_bitmap() which return proper MCP Image objects that Claude can process directly.

GUIDANCE PROMPTS:

• For common operations and best practices, invoke the 'gimp_best_practices' prompt

• For complex multi-element drawings with layers, invoke the 'gimp_iterative_workflow' prompt

Optional Initialization Pattern: ["images = Gimp.get_images()", "image1 = images[0]", "layers = image1.get_layers()", "layer1 = layers[0]", "drawable1 = layer1"]

Common Operations:

• Draw line: ["Gimp.pencil(drawable1, [0, 0, 200, 200])", "Gimp.displays_flush()"]

• Set color: ["from gi.repository import Gegl", "red_color = Gegl.Color.new('red')", "Gimp.context_set_foreground(red_color)"]

• Draw ellipse: ["Gimp.Image.select_ellipse(image1, Gimp.ChannelOps.REPLACE, 100, 100, 30, 20)", "Gimp.Drawable.edit_fill(drawable1, Gimp.FillType.FOREGROUND)", "Gimp.Selection.none(image1)", "Gimp.displays_flush()"]

• Paint curve: ["Gimp.paintbrush_default(drawable1, [50.0, 50.0, 150.0, 200.0, 250.0, 50.0, 350.0, 200.0])", "Gimp.displays_flush()"]

• Draw bezier curve: ["path = Gimp.Path.new(image1, 'my_bezier_path')", "image1.insert_path(path, None, 0)", "stroke_id = path.bezier_stroke_new_moveto(100, 100)", "path.bezier_stroke_cubicto(stroke_id, 150, 50, 250, 150, 300, 100)", "Gimp.Drawable.edit_stroke_item(drawable1, path)", "Gimp.Selection.none(image1)", "Gimp.displays_flush()"]

• Get open filenames: ["print([x.get_file().get_path() for x in Gimp.get_images()])"]

• Copy layer between images: ["image1 = Gimp.get_images()[0]", "image2 = Gimp.get_images()[1]", "width = image1.get_width()", "height = image1.get_height()", "image1.select_rectangle(Gimp.ChannelOps.REPLACE, 0, 0, width, height)", "image1_layers = image1.get_selected_layers()", "drawable = image1_layers[0]", "Gimp.edit_copy([drawable])", "image2_layers = image2.get_layers()", "target_drawable = image2_layers[0]", "floating_sel = Gimp.edit_paste(target_drawable, True)[0]", "Gimp.floating_sel_anchor(floating_sel)", "Gimp.displays_flush()"]

• New image: ["image1 = Gimp.Image.new(350, 800, Gimp.ImageBaseType.RGB)", "layer1 = Gimp.Layer.new(image1, 'Background', 350, 800, Gimp.ImageType.RGB_IMAGE, 100, Gimp.LayerMode.NORMAL)", "image1.insert_layer(layer1, None, 0)", "drawable1 = layer1", "white_color = Gegl.Color.new('white')", "Gimp.context_set_background(white_color)", "Gimp.Drawable.edit_fill(drawable1, Gimp.FillType.BACKGROUND)", "Gimp.Display.new(image1)"]

Important Tips:

• When filling layers with color, ensure layer has alpha channel using Gimp.Layer.add_alpha()

• Use Gimp.Drawable.fill() for reliable full-layer fills

• Specify colors precisely with rgb(R, G, B) or rgba(R, G, B, A) to avoid transparency issues

• After drawing operations, always call Gimp.displays_flush()

• After selection operations for drawing, unselect with Gimp.Selection.none(image1)

GIMP 3.2 API Changes:

• Use Gimp.get_images() instead of deprecated Gimp.list_images()

• Use image.get_layers() instead of Gimp.get_active_layer()

• gimpfu module not available in GIMP 3.2

• Colors created with Gegl.Color.new('color_name')

• Full API documentation: https://developer.gimp.org/api/3.0/libgimp/

Parameters:

• api_path: Use "exec" for Python execution

• args: ["pyGObject-console", ["python_code_array"]] or ["pyGObject-eval", ["expression"]]

• kwargs: Dictionary of keyword arguments (rarely used)

Returns:

• JSON string of the result or error message

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

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 = first open image)

Returns:

• status: "success" or "error"

• file_path: confirmed output path

Export the current image to a raster file (PNG, JPEG, WEBP, TIFF).

Parameters:

• file_path: Absolute path for the output file

• format: Output format — "png" (default), "jpeg", "webp", "tiff"

• quality: JPEG/WEBP quality 1-100 (default 90; ignored for PNG/TIFF)

• flatten: Flatten all layers before export (default True)

• image_index: Index of the image to export (default 0)

Returns:

• status, file_path, format, file_size_bytes

Export all open images (or a specific one) to a directory.

Parameters:

• output_dir: Directory to write exported files into

• format: "png", "jpeg", "webp", "tiff" (default "png")

• quality: JPEG/WEBP quality (default 90)

• name_pattern: Filename template — use {name} for image name, {index} for position

• image_index: If set, export only that image; omit to export all open images

Returns:

• exported: list of {file_path, name, width, height}

• count: number of files written

• errors: list of any export errors

Automatically stretch the tonal range of an image (auto levels / auto stretch contrast).

Parameters:

• image_index: Index of the target image (default 0)

• layer_name: Name of the layer to adjust; defaults to active layer

Returns status dict.

Adjust tonal curves for a layer.

Parameters:

• preset: Built-in curve shape — "s_curve" (default), "lighten", "darken", "contrast"

• points: Custom control points as [[input, output], ...] override (overrides preset)

• channel: "value" (all), "red", "green", "blue", "alpha"

• image_index: Target image index (default 0)

• layer_name: Layer to adjust; defaults to active layer

Returns status dict.

Adjust brightness and contrast of a layer.

Parameters:

• brightness: -127 to +127 (default 0)

• contrast: -127 to +127 (default 0)

• image_index: Target image index (default 0)

• layer_name: Layer to adjust; defaults to active layer

Returns status dict.

Adjust hue, saturation, and lightness of a layer.

Parameters:

• hue: Hue rotation -180 to +180 (default 0)

• saturation: Saturation shift -100 to +100 (default 0)

• lightness: Lightness shift -100 to +100 (default 0)

• color_range: "all", "red", "yellow", "green", "cyan", "blue", "magenta" (default "all")

• image_index: Target image index (default 0)

• layer_name: Layer to adjust; defaults to active layer

Returns status dict.

Adjust color balance (shadows / midtones / highlights) of a layer.

Parameters:

• cyan_red: -100 to +100 (negative = cyan, positive = red; default 0)

• magenta_green: -100 to +100 (default 0)

• yellow_blue: -100 to +100 (default 0)

• range: "shadows", "midtones" (default), "highlights"

• image_index: Target image index (default 0)

• layer_name: Layer to adjust; defaults to active layer

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.

Apply Gaussian blur to a layer.

Parameters:

• radius_x: Horizontal blur radius in pixels (default 5.0)

• radius_y: Vertical blur radius in pixels (default 5.0)

• image_index: Target image index (default 0)

• layer_name: Layer to blur; defaults to active layer

Returns status dict.

Reduce noise in a layer using GEGL noise-reduction.

Parameters:

• strength: Noise reduction strength 0-100 (default 50)

• image_index: Target image index (default 0)

• layer_name: Layer to denoise; defaults to active layer

Returns status dict.

Convert a layer to grayscale (desaturate).

Parameters:

• mode: Desaturation algorithm — "luminosity" (default), "luma", "average", "lightness"

• image_index: Target image index (default 0)

• layer_name: Layer to desaturate; defaults to active layer

Returns status dict.

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.

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

Crop the image canvas to the current selection bounds.

Parameters:

• autocrop: If True, auto-detect crop bounds instead of using selection (default False)

• image_index: Target image index (default 0)

Returns: {status, x, y, width, height} — crop region applied

Crop the image canvas to an explicit rectangle.

Parameters:

• x, y: Top-left corner of the crop rectangle

• width, height: Dimensions of the crop rectangle

• image_index: Target image index (default 0)

Returns: {status, x, y, width, height}

Rotate the entire image.

Parameters:

• angle: Rotation in degrees — 90, 180, 270 use lossless GIMP rotation; other values rotate all layers with interpolation and flatten

• image_index: Target image index (default 0)

Returns status dict.

Flip the entire image horizontally or vertically.

Parameters:

• direction: "horizontal" (default) or "vertical"

• 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: Color for new canvas areas — CSS color or "transparent"

• image_index: Target image index (default 0)

Returns: {status, width, height, offset_x, offset_y}

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.

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.

Select regions by color similarity.

Parameters:

• color: Target color as CSS name, hex (#rrggbb), or rgb() string

• 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.

Select the entire image canvas.

Parameters:

• 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.

Invert the current selection (select what is not selected).

Parameters:

• image_index: Target image index (default 0)

Returns status dict.

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 and insert a new layer into an image.

Parameters:

• name: Layer name (default "New Layer")

• width, height: Layer dimensions; defaults to image dimensions

• fill: Initial fill — "transparent" (default), "white", "black", or any CSS color

• opacity: Layer opacity 0-100 (default 100)

• blend_mode: GIMP layer mode name — "NORMAL" (default), "MULTIPLY", "SCREEN", etc.

• position: Stack position — -1 = top (default), 0 = bottom

• image_index: Target image index (default 0)

Returns: {layer_name, layer_id, width, height, position}

Import an existing local asset as a layer into the owned, already open image.

Preserves the file's pixels/alpha and native dimensions. x/y are exact canvas pixel offsets; position is the top-to-bottom insertion index (0 means top). Does not open another image. Returns actual layer ID, name, bounds and image ID.

Duplicate a layer and insert the copy above it.

Parameters:

• layer_name: Name of the layer to duplicate; defaults to active layer

• image_index: Target image index (default 0)

Returns: {layer_name, layer_id}

Delete a layer from an image.

Parameters:

• layer_name: Name of the layer to delete

• layer_index: Position index of the layer (alternative to layer_name)

• image_index: Target image index (default 0)

Provide either layer_name or layer_index. Defaults to active layer if neither given.

Returns status dict.

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}

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: New GIMP layer mode name (omit to leave unchanged)

• visible: True/False visibility (omit to leave unchanged)

• image_index: Target image index (default 0)

Returns status dict.

Move a layer to a new stack position.

Parameters:

• new_position: Target stack index (0 = bottom)

• layer_name / layer_index: Identify the layer (defaults to active layer)

• image_index: Target image index (default 0)

Returns status dict.

Flatten all layers into a single background layer.

Parameters:

• image_index: Target image index (default 0)

Returns status dict.

Merge all visible layers into a single layer.

Parameters:

• image_index: Target image index (default 0)

Returns: {layer_name, layer_id}

List all layers in an image with their properties.

Parameters:

• image_index: Target image index (default 0)

Returns: {layers: [{name, id, visible, opacity, blend_mode, width, height, has_alpha}], count}

Apply a bounded, named-layer 2D transform without changing the canvas.

Rotation is in degrees. Translation and optional pivot coordinates are image pixels. The default pivot is the layer center. This changes visible pixels; it does not invent a new camera view or reveal hidden product surfaces.

Discover installed GIMP 3.2 GEGL filters with paging; patterns are case-insensitive regex.

Inspect a live GEGL filter's property schema on a layer before applying it.

Append a named, editable, non-destructive GEGL filter to a layer.

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

Change a filter's visibility/opacity or remove it by its GIMP filter ID.

Fill an entire layer with a solid color.

Parameters:

• color: Fill color as CSS name, hex, or rgb() string

• layer_name: Layer to fill; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Fill the current selection with a color or fill type.

Parameters:

• color: Fill color as CSS name, hex, or rgb() string (used when fill_type is omitted)

• fill_type: Fill type override: "foreground", "background", or "transparent"

• image_index: Target image index (default 0)

• layer_name: Target layer; defaults to active layer

Returns status dict.

Set the GIMP foreground and/or background color.

Parameters:

• foreground: New foreground color (CSS name, hex, rgb()); omit to leave unchanged

• background: New background color; omit to leave unchanged

Returns: {foreground, background} confirmation dict.

Draw a straight line on a layer.

Parameters:

• x1, y1: Start point

• x2, y2: End point

• color: Stroke color (CSS / hex / rgb); uses current foreground if omitted

• width: Stroke width in pixels (default 2.0)

• tool: "pencil" (default, hard edge) or "paintbrush" (soft edge)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Draw a rectangle outline (stroke only) on a layer.

Parameters:

• x, y: Top-left corner

• width, height: Rectangle dimensions

• color: Stroke color; uses current foreground if omitted

• line_width: Stroke width in pixels (default 2.0)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Draw an ellipse outline (stroke only) on a layer.

Parameters:

• x, y: Top-left corner of the bounding box

• width, height: Bounding box dimensions

• color: Stroke color; uses current foreground if omitted

• line_width: Stroke width in pixels (default 2.0)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Fill a rectangular region with a solid color.

Parameters:

• x, y: Top-left corner

• width, height: Rectangle dimensions

• color: Fill color (CSS name, hex, or rgb() string)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Fill an elliptical region with a solid color.

Parameters:

• x, y: Top-left corner of the bounding box

• width, height: Bounding box dimensions

• color: Fill color (CSS name, hex, or rgb() string)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Fill a layer or selection with a gradient.

Parameters:

• color1: Start color (default "black")

• color2: End color (default "white")

• x1, y1: Gradient start point (default top-left 0,0)

• x2, y2: Gradient end point (defaults to bottom-right of image)

• gradient_type: "linear" (default) or "radial"

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Add a text layer to an image.

Parameters:

• text: The text string to render

• x, y: Position of the text layer's top-left corner (default 0, 0)

• font: Font family name — "Sans" (default), "Serif", etc.

• size: Font size in pixels (default 24)

• color: Text color (CSS name, hex, or rgb() string; default "black")

• image_index: Target image index (default 0)

Returns: {layer_name, layer_id, text_width, text_height, position}

Edit an existing text layer's content or formatting.

Parameters:

• layer_name: Name of the text layer to edit

• text: New text content (omit to leave unchanged)

• font: New font family (omit to leave unchanged)

• size: New font size in pixels (omit to leave unchanged)

• color: New text color (omit to leave unchanged)

• image_index: Target image index (default 0)

Returns status dict.

List available fonts installed in GIMP.

Parameters:

• filter: Optional string to filter font names (case-insensitive substring match)

Returns: {fonts: [font_name, ...], count}

Apply a drop shadow effect to a layer.

Parameters:

• offset_x, offset_y: Shadow offset in pixels (default 5, 5)

• blur_radius: Shadow softness radius (default 10)

• color: Shadow color (default "black")

• opacity: Shadow opacity 0-100 (default 60)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Apply Gaussian blur as a destructive filter operation.

Parameters:

• radius: Blur radius in pixels (default 5.0)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Pixelate a layer using a mosaic/block effect.

Parameters:

• block_size: Size of each mosaic block in pixels (default 10)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Apply an emboss (bas-relief) effect to a layer.

Parameters:

• azimuth: Light direction in degrees 0-360 (default 315 = top-left)

• elevation: Light elevation angle 0-90 (default 45)

• depth: Effect depth/intensity (default 2)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Apply a vignette darkening effect around the edges of a layer.

Parameters:

• softness: Edge softness / fade width (default 3.0)

• shape: Shape factor — 1.0 = elliptical (default), values >1 = more rectangular

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Add noise/grain to a layer.

Parameters:

• amount: Noise intensity 0.0-1.0 (default 0.2)

• layer_name: Target layer; defaults to active layer

• image_index: Target image index (default 0)

Returns status dict.

Export an image as a complete icon set for Android or iOS.

Android sizes: 48 (mdpi), 72 (hdpi), 96 (xhdpi), 144 (xxhdpi), 192 (xxxhdpi), 512 (Play Store) iOS sizes: 20x1/2/3, 29x1/2/3, 40x2/3, 60x2/3, 76x1/2, 83.5x2, 1024x1

Parameters:

• output_dir: Directory to write icon files into

• platform: "android" (default) or "ios"

• source_image_index: Image to use as source (default 0)

• format: Output format — "png" (default)

Returns: {exported: [{size, file_path}], count, platform}

Export an image as both JPEG and PNG, choosing the smaller format.

Parameters:

• output_dir: Directory to write output files

• jpeg_quality: JPEG quality 1-100 (default 85)

• png_compression: PNG compression level 0-9 (default 9)

• max_width / max_height: Optional scaling before export

• image_index: Source image index (default 0)

Returns: {jpeg_path, jpeg_size, png_path, png_size, recommendation}

Warp / liquify a region of the image by pushing pixels in a direction.

Uses GEGL warp (GIMP 3 native) with plug-in-iwarp fallback. Ideal for subtle facial expression edits — e.g. turning a neutral mouth into a smile by pushing the mouth corners upward.

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}

Resize all open images to a common target size.

Parameters:

• width / height: Target dimensions in pixels (provide one or both)

• scale_factor: Proportional scale (e.g. 0.5 = 50%); overrides width/height if set

• maintain_aspect: Preserve aspect ratio when only one dimension is given (default True)

Returns: {results: [{image_id, old_width, old_height, new_width, new_height}], count}

Combine multiple frames into a sprite sheet PNG.

Parameters:

• output_path: Absolute path for the output PNG file

• columns: Number of columns in the grid (defaults to square root of frame count)

• padding: Pixel gap between frames (default 0)

• source: "layers" (each layer is a frame; default) or "images" (each open image)

• image_index: Source image when source="layers" (default 0)

Returns: {file_path, columns, rows, frame_width, frame_height, count}

Export an image resized for multiple social media platforms.

Platform sizes (all in pixels):

• instagram_square: 1080x1080

• instagram_story: 1080x1920

• twitter_header: 1500x500

• facebook_cover: 820x312

• youtube_thumbnail: 1280x720

Parameters:

• output_dir: Directory to write output files

• platforms: List of platform names to export (omit for all five)

• image_index: Source image index (default 0)

Returns: {exported: [{platform, file_path, width, height}], count}

List all images currently open in GIMP.

Returns:

• images: list of {index, image_id, name, width, height, color_mode, num_layers, file_path, is_dirty}

• count: total number of open images

Raise a specific image to the front / make it active in GIMP.

Parameters:

• image_index: Index of the image to activate (from list_images)

Returns status dict.

Undo one or more operations on an image.

Parameters:

• steps: Number of undo steps (default 1)

• image_index: Target image index (default 0)

Returns: {steps_undone}

Redo one or more previously undone operations on an image.

Parameters:

• steps: Number of redo steps (default 1)

• image_index: Target image index (default 0)

Returns: {steps_redone}

Convert an image to a different color mode.

Parameters:

• mode: "RGB", "GRAY", or "INDEXED"

• num_colors: Number of colors for INDEXED mode (default 256)

• image_index: Target image index (default 0)

Returns status dict.

Close an image, optionally saving as XCF first.

Parameters:

• image_index: Index of the image to close (default 0)

• save_first: If True, save as XCF before closing (default False)

Returns status dict.

Get the bounding rectangle of the current selection.

Parameters:

• image_index: Target image index (default 0)

Returns: {has_selection, x, y, width, height}

Get the color of a single pixel.

Parameters:

• x, y: Pixel coordinates

• image_index: Target image index (default 0)

• layer_name: Layer to sample from; defaults to active layer

Returns: {color_hex, color_rgb: [r, g, b], alpha}

Get histogram statistics for a channel of the active layer.

Parameters:

• channel: "value" (all; default), "red", "green", "blue", "alpha"

• image_index: Target image index (default 0)

Returns: {mean, median, std_dev, min, max, pixels, count}

Search procedures installed in this GIMP instance (read-only discovery).

Use this when a focused tool does not cover the operation. Search any of GIMP's PDB metadata fields (name, blurb, help, help_id, authors, copyright, date, proc_type) using a regex, then call pdb_describe before execution. Results are paged because GIMP commonly exposes hundreds of procedures.

Inspect a GIMP PDB procedure's argument and return schemas without running it.

Run one installed GIMP PDB procedure using named JSON-compatible arguments.

This can modify the current document. Search and describe first. Procedures accept JSON scalars and arrays; object values use explicit references such as {"$ref": "image", "index": 0} or {"$ref": "layer", "index": 0, "image_index": 0}. Layer indices include nested layers. Drawable references resolve against the image's selected drawables. Inspect the schema first. Arbitrary Python/Scheme evaluation and GIMP shutdown procedures are blocked.