gimp-mcp

GIMP 3 を駆動してスクリプトによる画像編集を行う MCP サーバーです。切り抜き、リサイズ、アスペクト比合わせ、軽い色調補正、寸法仕様の検証、フォルダー単位の一括処理に対応しています。

Windows 上の GIMP 3.2.4 で構築・検証済みで、旧 2.x の Script-Fu インターフェースではなく、GIMP 3 の GObject Introspection Python API（gi.repository.Gimp）を使用しています。

何のためにあるか

同じ決定的な処理を繰り返し適用する必要があり、クリック操作ではなく記述で済ませたいワークフロー全般に使えます。

• 写真をターゲットのアスペクト比に切り抜く、または最大の中央正方形に切り抜く

• 画像フォルダーを、長辺が最大 2000px になるようにリサイズする

• 公開前に画像がサイズ・向きの要件を満たしているか確認する

• 1 回のパスで、撮影全体に同じ切り抜き・リサイズパイプラインを適用する

Related MCP server: gimp-mcp

注意すべき点: EXIF の向き

スマートフォンや多くのカメラの写真は、横向きで保存され、EXIF の向きタグによって表示時に回転されることがよくあります。誰もが 3000x4000 の縦向きとして見る写真が、4000x3000 で保存されている場合があります。

GIMP の非対話型ローダーはこのタグを適用しません。 素朴な「中央正方形に切り抜き」は、そのため間違った軸で切り抜かれ、横向きの画像を生成します。しかも、もっともらしい寸法を報告するため、出力を開くまで明らかに壊れているようには見えません。

このプロジェクトのすべての読み込みは load_image() を経由し、最初に Gimp.Image.policy_rotate() を呼び出すため、すべてのジオメトリ、およびこのサーバーが報告するすべての寸法は、表示された向き、つまり閲覧者が実際に見る向きになります。これはテストでカバーされています。

アーキテクチャ

2 つの実行バックエンド、1 つの共有操作ランタイム:

                    ┌───────────────────────────────┐
  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 ポインターを書き込みます。これにより、操作コードのコピーがディスク上に 1 つだけ存在します。

バックエンドの選択。 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.x が選択され、インポート時に失敗します。

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 がインポート可能であればです。

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

オプションの環境変数:

ツール

検査

単一画像

バッチ

バッチ全体は 1 回の GIMP 呼び出し内で実行されます。GIMP のコンソールは起動に数秒かかるため、ファイルごとにプロセスを生成すると遅くなります。小さなフォルダーではファイルあたり約 2.4 倍安価であると測定され、フォルダーサイズが大きくなるにつれて節約は大きくなります。失敗したファイルは実行を中止せず、errors に入り、残りは続行します。

ライブ制御（ブリッジプラグインが必要）

GIMP でブリッジを開始: フィルター > 開発 > MCP ブリッジを開始。

画像仕様

check_image_spec、fit_to_spec、およびそのバッチ相当は、1 つの仕様モデルを共有します。すべての制約はオプションです。0 は制限なしを意味し、向き any は向きの要件がないことを意味します。

fit_to_spec は、3 つの順序付きステップで仕様を満たします: 向きを修正するための切り抜き、最小値に達するためのアップスケール、最大値を尊重するためのダウンスケール。すでに満たされている制約は、フレーミングを変更しません。

// 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 モードで埋め込みプロファイルを含む画像を開くとき。ヘッドレスモードでは表示されません。これもバッチ作業がヘッドレスバックエンドを使用するもう 1 つの理由です。

バッチがタイムアウトした — デフォルトは実行全体で 600 秒です。非常に大きなフォルダーではより多くの時間が必要になる場合があります。

既知の制限

• ライブ制御は軽くしか試されていない。 動作確認はされている（画像を開く、一覧表示、スクリーンショット、ライブ編集、ブリッジ経由でのクロップがヘッドレスと同一の出力で可能）が、ヘッドレス経路に比べ使用量ははるかに少ない。信頼できるのはヘッドレスと考えること。

• ブリッジは設計上、任意のPythonを実行する。 ループバック専用で、自動起動ではなく手動起動だが、マシン上のlocalhostに到達できるものは、実行中は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を参照。