GIMP Local MCP

GIMP Local MCP is a local-first Model Context Protocol server for controlling GIMP 3 through an LLM. The LLM chooses an operation through structured MCP calls; GIMP owns the image manipulation, rendering, file loading, and exporting. Images and files remain on the user’s machine.

This v0.1 implementation favors a small, composable architecture over hundreds of one-off wrappers.

Philosophy

• GIMP owns pixels. This project does not generate replacement pixels or call cloud image services.

• Routine edits use ergonomic tools with stable image and layer IDs.

• The live GIMP PDB is the long-term path to broad coverage, with structured invocation rather than raw Scheme input.

• File writes are explicit and never overwrite existing targets by default.

• The bridge preserves GIMP’s undo history and groups multi-step operations when the operation needs multiple PDB calls.

Related MCP server: GIMP MCP

Architecture

Natural language
      |
      v
MCP host (Codex, Claude, custom client)
      |
      | MCP stdio / JSON-RPC
      v
gimp-local-mcp
  ergonomic tools ---> GimpService ---> safe Scheme serializer
                              |                  |
                              +--> PDB catalog/invoker
                                                   |
                                                   v
                                    Script-Fu TCP framing (127.0.0.1:10008)
                                                   |
                                                   v
                                             GIMP 3 Script-Fu server

The official MCP Python SDK is used for the server. Script-Fu socket and framing logic is isolated in gimp/transport.py and gimp/protocol.py; tool functions do not manipulate sockets directly.

Requirements

• Python 3.10 or newer

• GIMP 3.x

• A running GIMP 3 Script-Fu server

GIMP is not required for the ordinary unit test suite.

GIMP 3 setup

1. Start GIMP 3.

2. Open Filters → Development → Script-Fu → Start Server.

3. Keep the listener on 127.0.0.1 and port 10008 unless you have a specific reason to change it.

4. Start the MCP server after the Script-Fu server is listening.

GIMP’s Script-Fu server accepts a three-byte G/16-bit-length request frame and returns a four-byte G/error/16-bit-length response frame. GIMP allows one Script-Fu client at a time; this server maintains one reconnectable client connection.

Installation

From a checkout:

python -m pip install -e '.[dev]'

For a runtime-only installation:

python -m pip install .

Run the server

gimp-local-mcp serve

With no subcommand, gimp-local-mcp also starts the stdio MCP server. Stdout is reserved for MCP protocol traffic; diagnostics go to stderr.

Check the local connection independently:

gimp-local-mcp doctor

doctor prints Python details, the configured endpoint, local-only status, Script-Fu reachability, GIMP version, and open-image count. A connection refusal is expected until GIMP’s Script-Fu server is started.

Codex configuration

Add a project-local MCP entry in the Codex configuration used for this checkout. The exact location depends on the Codex client version; do not modify global configuration automatically.

[mcp_servers.gimp-local-mcp]
command = "gimp-local-mcp"
args = ["serve"]

If the command is not on the client’s PATH, use the absolute path to the virtual-environment executable or launch it with Python:

[mcp_servers.gimp-local-mcp]
command = "python"
args = ["-m", "gimp_local_mcp.cli", "serve"]

Configuration

Defaults work with a standard local GIMP setup:

Remote connections are rejected unless GIMP_MCP_ALLOW_REMOTE=true is set. Localhost-only operation is the secure default.

MCP tools

The current server registers 40 tools across these groups:

• Session: gimp_status, gimp_capabilities, list_open_images, get_active_image, get_image_info

• Files and images: open_image, create_image, save_xcf, export_image, close_image

• Layers: list_layers, get_layer_info, create_layer, duplicate_layer, rename_layer, delete_layer, set_layer_visibility, set_layer_opacity, set_layer_mode, move_layer, merge_down

• Transforms: resize_image, resize_canvas, crop_image, rotate_image, flip_image

• Selection: select_all, select_none, invert_selection, select_rectangle, select_ellipse, select_layer_alpha

• Adjustments and undo: brightness_contrast, hue_saturation, desaturate, undo, redo

• PDB: search_pdb, describe_pdb_procedure, invoke_pdb_procedure

invoke_pdb_procedure accepts JSON-compatible structured values, including { "scheme_symbol": "RGB" } for a GIMP enum. It does not accept Scheme source, Python, shell commands, or arbitrary evaluation. Runtime PDB counts and documentation are used when available. Procedure descriptions now include a bounded typed-metadata state (available, partial, unavailable, or malformed) plus argument/return records when a trusted structured adapter reports them. The default Script-Fu TCP adapter reports argument metadata as unavailable because Script-Fu does not expose a stable GimpProcedure/GParamSpec representation; no signatures or types are guessed. Named-argument validation is performed only when trustworthy names are actually available.

Example requests

• “Open this image and crop it to 16:9 around the subject.”

• “Duplicate the background layer, desaturate it, and reduce its opacity to 40%.”

• “Resize this to 2048 pixels wide while preserving aspect ratio.”

• “Export a JPEG copy at this path without overwriting anything.”

• “What layers are currently in this document?”

• “Find a GIMP procedure capable of applying Gaussian blur and describe its arguments.”

The final request is supported through PDB search and description; the current description reports procedure counts, documentation, and the explicit argument-metadata capability state. Rich argument records remain unavailable through the default Script-Fu bridge until a live, trustworthy adapter is available.

Security model

See SECURITY.md. In brief:

• the MCP server is stdio-first and connects to loopback by default;

• no shell, Python eval, raw Script-Fu MCP tool, or cloud image API exists;

• procedure names and structured values are validated before serialization;

• strings and paths are escaped as Scheme literals;

• output paths must be explicit, normalized, and non-overwriting unless requested;

• closing a dirty image requires an explicit discard choice.

Limitations

• A live GIMP 3 installation is not available in this development environment, so integration tests are skipped here.

• Export metadata behavior uses GIMP’s configured defaults in v0.1; no hidden metadata is added or removed.

• The initial adjustment tools call stable legacy PDB adjustment procedures that GIMP 3.2 marks deprecated in favor of non-destructive filters. Structured filter configuration is a high-value follow-up.

• get_active_image uses GIMP’s default display; explicit image IDs are more reliable for multi-window workflows.

• Multi-call layer creation and duplication are grouped into one GIMP undo step. Additional composite operations should adopt the same internal helper as they are added.

Roadmap

1. Validate the high-level vertical slices against GIMP 3.2+ on Linux, macOS, and Windows.

2. Validate a GIMP 3-compatible structured PDB metadata adapter for argument names, types, defaults, and enum choices; keep the explicit unavailable fallback when Script-Fu cannot provide it.

3. Add structured non-destructive GEGL filter operations for brightness/contrast, levels, curves, hue/saturation, and Gaussian blur.

4. Improve recursive group-layer inspection and image/layer selection semantics.

5. Add explicit export metadata policies and more file-format option models.

6. Add safe, persistent capability caching with GIMP version invalidation.

Development

ruff format src tests
ruff check src tests
pytest -q

Live tests are marked integration and skip when 127.0.0.1:10008 is unavailable. See CONTRIBUTING.md and AGENTS.md for repository invariants.