# GIMP Agent MCP

Connects AI coding agents to GIMP 3 for layered image editing, pixel inspections, and automated sprite packing. It preserves your layer hierarchy and exports native XCF files.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: SarutobiSasuke8
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/SarutobiSasuke8/gimp-agent-mcp
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/mcp/gimp-agent-mcp

## What it does

This MCP server translates agent actions into GIMP 3 commands directly inside an active GUI window or headlessly. The agent can modify text layers, measure alpha channels, and generate texture atlases. Edits on a single image group into one undo step. A single Ctrl+Z reverts everything.

Prerequisites include GIMP 3.2.x, Python 3.11+, and `uv` on the local machine. The bridge starts from the GIMP interface under Filters → Development → Start Agent Bridge. Because the server requires a local GIMP process, remote setups without GIMP installed will fail immediately. An optional segmentation module handles local background removal.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `GIMP_AGENT_ALLOW_PYTHON` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GIMP_AGENT_ALLOW_PYTHON=<GIMP_AGENT_ALLOW_PYTHON> --transport stdio gimp-agent-mcp -- uvx gimp-agent-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from gimp-agent-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add gimp-agent-mcp --env GIMP_AGENT_ALLOW_PYTHON=<GIMP_AGENT_ALLOW_PYTHON> -- uvx gimp-agent-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from gimp-agent-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "gimp-agent-mcp": {
            "command": "uvx",
            "args": [
                "gimp-agent-mcp"
            ],
            "env": {
                "GIMP_AGENT_ALLOW_PYTHON": "<GIMP_AGENT_ALLOW_PYTHON>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from gimp-agent-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "gimp-agent-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "gimp-agent-mcp"
            ],
            "env": {
                "GIMP_AGENT_ALLOW_PYTHON": "<GIMP_AGENT_ALLOW_PYTHON>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from gimp-agent-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GIMP_AGENT_ALLOW_PYTHON=<GIMP_AGENT_ALLOW_PYTHON> gimp-agent-mcp uvx gimp-agent-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from gimp-agent-mcp <command>

## When to use it
- update text layers on graphic assets without rasterizing them
- convert illustration artwork into Telegram stickers with borders
- assemble animation frames into sprite sheets with JSON data
- process image batches headlessly without opening editor windows

## Example prompts
- Update the headline on this graphic while preserving text layers and grouping the edits into one undo step.
- Turn this transparent image into a 512x512 Telegram sticker with a white outline and drop shadow.
- Pack these frames into a sprite sheet, export the master XCF, and verify the atlas JSON.

## Similar
- [Next AI Draw.io](https://affpapa.org/en/nevibecode/mcp/next-ai-drawio.md) — MCP server · ★ 36427
- [tldraw](https://affpapa.org/en/nevibecode/mcp/tldraw.md) — MCP server · ★ 51104
- [Figma-Context-MCP](https://affpapa.org/en/nevibecode/mcp/figma-context-mcp.md) — MCP server · ★ 16073
- [Agent-Native Assets](https://affpapa.org/en/nevibecode/mcp/agent-native-assets.md) — MCP server · ★ 7527
- [Remove AI Watermarks](https://affpapa.org/en/nevibecode/mcp/remove-ai-watermarks.md) — MCP server · ★ 6144
- [Dembrandt](https://affpapa.org/en/nevibecode/mcp/dembrandt.md) — MCP server · ★ 3851

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md