gimp-mcp

GIMP 3을 구동하는 MCP 서버로, 스크립트 기반 이미지 편집을 위한 도구입니다: 자르기, 크기 조정, 종횡비 맞추기, 가벼운 색상 보정, 치수 사양 검증, 폴더 전체에 대한 일괄 처리를 제공합니다.

Windows의 GIMP 3.2.4에서 빌드 및 검증되었으며, 기존 2.x Script-Fu 인터페이스 대신 GIMP 3의 GObject Introspection Python API(gi.repository.Gimp)를 사용합니다.

용도

동일한 결정적(deterministic) 처리를 반복적으로 적용해야 하고, 클릭으로 처리하기보다 설명으로 처리하고 싶은 모든 워크플로에 적합합니다:

• 사진을 대상 종횡비로 자르거나, 가장 큰 중앙 정사각형으로 자르기

• 이미지 폴더의 가장 긴 변이 최대 2000px가 되도록 크기 조정

• 게시 전에 이미지가 크기/방향 요구 사항을 충족하는지 확인

• 한 번의 패스로 전체 촬영본에 동일한 자르기-크기조정 파이프라인 적용

Related MCP server: gimp-mcp

가장 주의해야 할 문제: EXIF 방향

휴대폰과 많은 카메라의 사진은 EXIF 방향 태그와 함께 가로 방향으로 저장되는 경우가 흔하며, 이 태그는 뷰어에게 회전하라고 지시합니다. 모두가 3000x4000 세로 사진으로 보는 사진이 4000x3000으로 저장되어 있을 수 있습니다.

GIMP의 비대화형 로더는 해당 태그를 적용하지 않습니다. "중앙 정사각형 자르기"를 단순하게 적용하면 잘못된 축을 자르게 되어 옆으로 누운 이미지가 생성됩니다. 그런데도 그럴듯한 치수가 보고되므로, 출력물을 열기 전까지는 명백히 잘못된 것이 눈에 띄지 않습니다.

이 프로젝트의 모든 로드는 load_image()를 거치며, 이 함수는 먼저 Gimp.Image.policy_rotate()를 호출하므로 모든 지오메트리 — 그리고 이 서버가 보고하는 모든 치수 — 는 표시 방향(displayed orientation), 즉 뷰어가 실제로 보는 방향을 기준으로 합니다. 이는 테스트로 검증됩니다.

아키텍처

두 가지 실행 백엔드, 하나의 공유 작업 런타임:

                    ┌───────────────────────────────┐
  MCP client ──────►│  gimp_mcp/server.py (stdio)   │
                    └───────────┬───────────────────┘
                                │
              ┌─────────────────┴──────────────────┐
              ▼                                    ▼
   HeadlessBackend                        BridgeBackend
   spawns gimp-console-3.exe              TCP 127.0.0.1:50472
   (no running GIMP needed)               (into a running GIMP)
              │                                    │
              ▼                                    ▼
      bootstrap.py                    plug-ins/gimp-mcp-bridge/
              │                                    │
              └──────────────┬─────────────────────┘
                             ▼
              gimp_mcp/gimp_runtime.py
              THE single source of truth for every
              image operation. Both paths share it,
              so batch and live cannot drift apart.

install_plugin.py는 gimp_runtime.py를 복사하는 대신 설치된 플러그인 옆에 runtime_path.txt 포인터를 작성하므로, 작업 코드의 단일 사본만 디스크에 존재합니다.

백엔드 선택. headless가 기본값이며 모든 일괄 및 결정적 작업에 사용됩니다 — 열려 있는 GIMP가 필요 없고 신뢰할 수 있는 경로입니다. bridge는 이미 열려 있는 문서에 대해 실시간 작업을 할 때 사용합니다. 두 백엔드 모두 픽셀 단위로 동일한 출력을 생성하는 것으로 검증되었습니다.

TCP를 사용하는 이유, D-Bus가 아닌 이유

기존의 실시간 GIMP 제어 프로젝트는 D-Bus를 사용하지만, D-Bus는 Windows에 존재하지 않습니다. 루프백 TCP 소켓은 동일한 기능을 달성하면서 크로스 플랫폼입니다. 127.0.0.1에만 바인딩되며 네트워크에 절대 노출되지 않습니다.

설치

GIMP 3.x(3.2.4 기준으로 개발됨)와 mcp Python 패키지가 필요합니다.

mcp 의존성에 대한 참고. 이 프로젝트는 mcp 1.x SDK를 대상으로 하며 mcp>=1.0,<2로 고정되어 있습니다. 2.0 버전은 mcp.server.fastmcp를 제거하고 FastMCP를 MCPServer로 이름을 바꾸었습니다. 2.0으로의 포팅은 아직 완료되지 않았으며, 고정하지 않고 설치하면 2.x가 설치되어 import 시 실패합니다.

pip install -r requirements.txt
python install_plugin.py          # install the bridge plug-in (optional)
python install_plugin.py --list   # show detected GIMP config dirs

브리지 플러그인은 실시간 제어 도구에만 필요합니다. 일괄 및 단일 이미지 도구는 GIMP에 아무것도 설치하지 않고도 작동합니다.

플러그인 위치

install_plugin.py는 버전을 하드코딩하는 대신 실제로 존재하는 GIMP 3.x 설정 디렉터리를 탐색합니다. Windows에서는 다음과 같습니다:

%APPDATA%\GIMP\3.2\plug-ins\gimp-mcp-bridge\gimp-mcp-bridge.py

버전이 포함된 디렉터리(GIMP 3.2의 경우 3.2, 3.0이 아님)이며, GIMP 3에서는 각 플러그인이 .py 파일과 이름이 일치하는 폴더에 있어야 합니다. Linux와 macOS에서 설치 프로그램은 각각 ~/.config/GIMP/3.x/와 ~/Library/Application Support/GIMP/3.x/를 찾습니다.

MCP 서버 등록

패키지를 설치하면 gimp-mcp 콘솔 스크립트가 제공되며, 이는 작업 디렉터리에 의존하지 않으므로 등록하기에 가장 깔끔한 방법입니다:

python -m venv .venv
.venv/Scripts/python -m pip install -e .     # .venv/bin/python on Unix

{
  "mcpServers": {
    "gimp": {
      "type": "stdio",
      "command": "/path/to/gimp-mcp/.venv/Scripts/gimp-mcp.exe",
      "args": []
    }
  }
}

Claude Code에서는 다음과 같은 한 줄 명령으로 동일하게 처리할 수 있습니다:

claude mcp add gimp --scope user -- /path/to/gimp-mcp/.venv/Scripts/gimp-mcp.exe

해당 인터프리터에서 mcp를 import할 수 있다면 모듈을 직접 실행해도 됩니다:

{
  "mcpServers": {
    "gimp": {
      "command": "python",
      "args": ["-m", "gimp_mcp"],
      "cwd": "/path/to/gimp-mcp"
    }
  }
}

선택적 환경 변수:

도구

검사

단일 이미지

일괄 처리

전체 일괄 처리는 하나의 GIMP 호출 안에서 실행됩니다. GIMP 콘솔은 시작하는 데 수 초가 걸리므로 파일별로 프로세스를 생성하면 느릴 것입니다 — 작은 폴더의 경우 파일당 약 ~2.4배 저렴한 것으로 측정되었으며, 폴더가 클수록 절감 효과는 커집니다. 실패한 파일이 실행을 중단하지 않으며, errors에 기록되고 나머지는 계속 진행됩니다.

실시간 제어(브리지 플러그인 필요)

GIMP에서 브리지 시작: 필터 > 개발 > MCP 브리지 시작.

이미지 사양

check_image_spec, fit_to_spec 및 해당 일괄 버전은 하나의 사양 모델을 공유합니다. 모든 제약 조건은 선택 사항입니다 — 0은 제한 없음을 의미하고, 방향 any는 방향 요구 사항이 없음을 의미합니다.

fit_to_spec는 세 단계의 순서로 사양을 충족합니다: 방향을 수정하기 위한 자르기, 최소 크기에 도달하기 위한 업스케일, 최대 크기를 존중하기 위한 다운스케일. 이미 충족된 제약 조건은 프레이밍을 변경하지 않습니다.

// A square image at least 1000x1000, capped at 2000x2000
{ "orientation": "square", "min_width": 1000, "min_height": 1000,
  "max_width": 2000, "max_height": 2000 }

색상 조정은 의도적으로 제한적입니다

adjust_image는 밝기/대비를 -0.5..0.5로 제한하며, 범위를 벗어나는 값은 클램프하지 않고 거부합니다. 약 ±0.15를 넘는 값은 사진의 특성을 눈에 띄게 바꾸며, 이는 이미지가 실제 대상을 충실히 표현해야 할 때 중요합니다. 채도 부스트나 "자동 향상"은 의도적으로 없습니다.

검증

테스트 스위트 실행:

python -m pytest tests/ -v

실제 이미지가 필요한 테스트는 이미지를 지정하지 않으면 건너뜁니다:

export GIMP_MCP_TEST_IMAGE=/path/to/photo.jpg          # ideally EXIF-rotated
export GIMP_MCP_TEST_REFERENCE=/path/to/photo-square.jpg

GIMP_MCP_TEST_REFERENCE는 GIMP_MCP_TEST_IMAGE의 독립적으로 생성된 중앙 정사각형 자르기여야 합니다 — 예를 들어 GIMP에서 수동으로 자른 것입니다. 핵심 테스트는 crop_square가 오류 없이 실행되는 것에 그치지 않고 해당 참조를 재현한다는 것을 검증합니다.

개발 중 사용된 참조 사진(EXIF 방향 6의 4000x3000 JPEG, 3000x4000으로 표시됨)에서:

crop_square vs hand-made reference : mean abs diff 0.236, max 18, outliers 0.0014%
same crop via the bridge backend   : mean abs diff 0.236, max 18, outliers 0.0014%

그 잔차는 JPEG 재인코딩 노이즈입니다 — 재인코딩만으로도 평균 ~0.5가 발생하며 — 지오메트리 차이가 아니며, 두 백엔드는 정확히 일치합니다.

테스트 스위트는 또한 표시 방향 보고, 방향 및 최소 크기 사양, 범위를 벗어난 자르기 거부, 범위를 벗어난 조정 거부, 밝기가 픽셀을 올바른 방향으로 이동하는지, 체인 파이프라인, 종횡비 자르기, 폴더 전체 일괄 처리, 읽기 전용 감사, 누락된 파일에 대한 명확한 오류, 실제 MCP stdio 프로토콜에 대한 전체 통과를 다룹니다.

문제 해결

gimp-console not found — GIMP_CONSOLE에 gimp-console-3.exe의 전체 경로를 설정하세요.

브리지 도구가 "Could not reach the GIMP bridge"로 실패 — GIMP가 열려 있지 않거나 브리지가 시작되지 않았습니다. 필터 > 개발 > MCP 브리지 시작을 실행하세요. gimp_status는 두 백엔드를 동시에 표시합니다.

설치 후 메뉴 항목이 보이지 않음 — GIMP를 다시 시작하세요. 플러그인은 시작 시에만 스캔합니다. 레이아웃이 plug-ins/gimp-mcp-bridge/gimp-mcp-bridge.py인지 확인하세요 (폴더 이름은 파일 이름과 일치해야 합니다).

플러그인 진단 — GIMP 플러그인은 별도 프로세스이며, Windows에서 GIMP가 GUI 앱으로 실행될 때 stderr가 보이지 않습니다. 브리지는 설치된 플러그인 옆의 bridge.log에 기록합니다.

색상 프로필 대화상자가 GIMP 시작을 차단 — GUI 모드에서 임베디드 프로필이 있는 이미지를 열 때 발생합니다. 헤드리스 모드에서는 나타나지 않으며, 이것이 일괄 작업이 헤드리스 백엔드를 사용하는 또 다른 이유입니다.

일괄 처리 시간 초과 — 기본값은 전체 실행에 600초입니다. 매우 큰 폴더는 더 많은 시간이 필요할 수 있습니다.

알려진 제한 사항

• 라이브 제어는 가볍게만 검증되었다. 작동이 확인되었지만(이미지 열기, 목록, 스크린샷, 라이브 편집, 브리지를 통한 크롭이 헤드리스와 동일한 출력으로 수행됨), 헤드리스 경로보다 사용량이 훨씬 적다. 헤드리스를 신뢰할 수 있는 경로로 취급하라.

• 브리지는 설계상 임의의 Python을 실행한다. 루프백 전용이며 자동이 아닌 수동으로 시작되지만, 머신의 localhost에 도달할 수 있는 모든 것은 GIMP가 실행되는 동안 GIMP를 구동할 수 있다. 사용하지 않을 때는 중지하라.

• 브리지 시작은 자체 플러그인 프로세스를 차단한다 — 이것이 브리지를 살아 있게 유지하는 방식이다. GIMP의 UI를 멈추지는 않지만, GIMP는 플러그인이 실행 중인 것으로 표시한다.

• GUI 메뉴 항목 자체는 자동화 테스트로 검증되지 않았다. 해당 항목이 호출하는 절차는 검증되었지만, 클릭 경로는 검증되지 않았다.

• Windows만 검증되었다. 코드 경로는 크로스 플랫폼이며 설치 프로그램이 Linux/macOS 구성 디렉터리를 처리하지만, 둘 다 테스트되지 않았다.

• mcp 2.x SDK는 아직 지원되지 않는다 — Install 아래의 참고 사항을 보라.

• AI 배경 제거나 스타일 전환은 없다. 일부 유사 프로젝트는 작동하는 구현 없이 이를 광고하지만, 여기서는 의도적으로 주장하지 않는다.

선행 기술에 대한 참고 사항

브리지를 노출하는 GIMP 측 플러그인과 클라이언트로 연결되는 독립형 MCP 서버 프로세스 간의 분리는 이 문제에 자연스러운 형태이며 다른 GIMP MCP 프로젝트에서도 사용된다. 배치 처리와 프리셋 스타일 파이프라인은 여러 프로젝트에 공통적이다. 라이브 캔버스 제어는 다른 곳에서 D-Bus를 통해 존재하지만, 여기서는 Windows 지원을 위해 루프백 TCP로 대체되었다. 이들 중 어느 것에서도 코드를 복사하지 않았다. Windows 특정 사항 — 실제 플러그인 경로, 플러그인 프로세스 수명, 실행 콜백 시그니처, EXIF 동작 — 은 GIMP 3.2.4에 대해 직접 확인되었다.

라이선스

MIT — LICENSE 참조.