GIMP 3 MCP

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 as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); default "black" - image_index: Target image index (default 0) Returns: {layer_name, layer_id, text_width, text_height, position}

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

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

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 as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); 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 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, whole number 1-100 (default 2) - 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. Same as blur with equal horizontal and vertical radii. 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.

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.

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 a vignette darkening effect around the edges of a layer. Parameters: - softness: Edge softness / fade width, 0.0-1.0 (default 0.8) - shape: "circle" (default), "square", "diamond", "horizontal" or "vertical" - layer_name: Target layer; defaults to active layer - image_index: Target image index (default 0) Returns status dict.

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.

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

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}

Apply Gaussian blur to a layer. Same as apply_gaussian_blur, but with separate horizontal and vertical radii. 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.

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 - Each array item runs as its own exec(): put a multi-line block (for/if/def) in ONE item with embedded newlines, not split across items - Only print() output is returned (one string per item); bare expressions are not echoed. To get values back, use args[0] = "pyGObject-eval" with a list of expressions, e.g. ["pyGObject-eval", ["len(Gimp.get_images())"]] - 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 as hex ("#rrggbb"): rgb() floats are read as linear light, and unknown color names silently become a translucent cyan - 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 are created with Gegl.Color.new("#rrggbb") - 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

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 > MCP > Start MCP Server.

Close an image, optionally saving as XCF first. Closes images opened with new_canvas or open_image, and images that have no window. GIMP 3 gives plug-ins no way to close a window opened from GIMP's own menus, so for those images this returns an error and they must be closed in GIMP. Parameters: - image_index: Index of the image to close (default 0 = most recently opened) - save_first: If True, save as XCF before closing (default False). An image opened from an XCF file is saved over that file. Any other image is saved as a new .xcf next to the file it came from (in the temp directory if it has none), named name-2.xcf, name-3.xcf, ... instead of overwriting an existing file. Without save_first, unsaved changes are discarded. Returns: {closed_image_id, saved_to (XCF path, or null)}

Convert an image to a different color mode. Parameters: - mode: "RGB", "RGBA", "GRAY", "GRAYA" (the A forms also add alpha to every layer) or "INDEXED" - num_colors: Number of colors for INDEXED mode, 1-256 (default 256) - 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: "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) - opacity: Layer opacity 0-100 (default 100) - blend_mode: 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) - position: Stack index, 0 = top of the stack; -1 (default) = directly above the active layer - image_index: Target image index (default 0) Returns: {layer_name, layer_id, width, height, position}

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}

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

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.

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.

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 as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); 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 a straight line on a layer. Parameters: - x1, y1: Start point - x2, y2: End point - color: Stroke color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); 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 as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); 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.

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}

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 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) - image_index: Target image index (default 0) All values are checked before anything changes. A font name GIMP does not have falls back to a similar or default font, so check the returned font. Returns: {layer_name (it can change with the text), text, font, size}

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 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 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}

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, in list_layers order; default) or "images" (each open image's visible result, in list_images order) - image_index: Source image when source="layers" (default 0) Each cell is the size of the first frame; bigger frames are cropped. Transparency is kept. Returns: {file_path, columns, rows, frame_width, frame_height, count}

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 (fastest, largest) to 9 (smallest; default) - 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}

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 as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple) - layer_name: Target layer; defaults to active layer - image_index: Target image index (default 0) Returns status dict.

Fill an entire layer with a solid color. Parameters: - color: Fill color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple) - layer_name: Layer to fill; 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 as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple) - layer_name: Target layer; 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 hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple) (used when fill_type is omitted) - fill_type: Instead of color: "foreground" or "background" (GIMP's current colors, see set_colors), "pattern", or "transparent" (clears the selection). Give color or fill_type. - image_index: Target image index (default 0) - layer_name: Target layer; defaults to active layer Returns status dict.

Flatten all layers into a single background layer. Parameters: - 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.

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 as sRGB hex ("#rrggbb", as tools accept) and alpha 0-1 - Current brush and its properties - Opacity setting (0-100%) - Paint mode, named like set_layer_properties blend modes (e.g. "NORMAL") - Feather state and radius [x, y] - 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

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

Get histogram statistics for one channel of a layer. Parameters: - channel: "value" (all; default), "red", "green", "blue", "alpha" - image_index: Target image index (default 0) - layer_name: Layer to measure; defaults to the active layer Returns: {layer, mean, std_dev, median (on a 0-255 scale), pixels (in the layer), count (pixels in range), percentile (fraction of pixels in range)}

Get an open image in GIMP as an Image object with optional scaling and region selection. Renders the image data (all visible layers), independent of GIMP's zoom or scroll. 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: Box to scale the image into, preserving aspect ratio (smaller images are enlarged). Omit for full resolution. - region: Dictionary with keys (image pixel coordinates, integers): - origin_x, origin_y: Top-left corner of region to extract - width, height: Dimensions of region to extract - max_width, max_height: Optional box to scale the region into (small regions are enlarged) Other keys (such as x/y) are rejected. - image_index: Which open image to render (default 0 = most recently opened; see list_images) 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}) get_state_snapshot is a shorter way to ask for the same image. Returns: the image as PNG. Fails if no image is open, the region is invalid, or export fails.

Get metadata about an open image in GIMP without the bitmap data. Parameters: - image_index: Which open image to describe (default 0 = most recently opened; see list_images) Returns detailed information about the 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 the color of a single pixel. sample_color does the same and can average over a radius; it reports alpha as 0-1, this tool as 0-255. Parameters: - x, y: Image pixel coordinates - image_index: Target image index (default 0) - layer_name: Layer to sample when sample_merged is false; defaults to active layer - sample_merged: true (default) samples what is visible across all layers; false samples only one layer Returns: {color_hex (sRGB), color_rgb: [r, g, b], alpha (0-255), sampled (what was read)}

Get the bounding rectangle of the current selection. Parameters: - image_index: Target image index (default 0) Returns: {has_selection, x, y, width, height}

Return a live visual snapshot of the current image state — no file save needed. A shortcut for get_image_bitmap with a single max_size and x/y region keys. 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: Longest side of the returned PNG in pixels (default: 512). The image or region is scaled to fit, so small regions are enlarged: positions in the snapshot are not image coordinates (multiply by region width / snapshot width). - region: Optional dict {x, y, width, height} in image pixels to zoom into an 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. <edit operations> 3. get_state_snapshot() ← see result, decide next step 4. <more edits> 5. get_state_snapshot(region={"x":200,"y":300,"width":100,"height":80}) 6. export_image when satisfied

Fill a layer or selection with a gradient. With an active selection, only the selected part of the layer is filled. Parameters: - color1: Start color as hex "#rrggbb" or a basic name (black, white, gray, silver, red, maroon, yellow, olive, lime, green, aqua, teal, blue, navy, fuchsia, purple); default "black" - color2: End color, same formats; default "white" - x1, y1: Gradient start point in image pixels (default 0, 0) - x2, y2: Gradient end point in image pixels (default: the image's bottom-right corner); must differ from the start point - gradient_type: "linear" (default) or "radial" - layer_name: Target layer; defaults to active layer - image_index: Target image index (default 0) Returns status dict.