GIMP Agent MCP

GIMP Agent MCP

AI エージェントで GIMP を編集できます。レイヤーはそのまま維持され、変更内容も確認できます。

Claude、Codex、Cursor などの MCP クライアントを GIMP 3 に接続できます。エージェントは開いているウィンドウで作業し、結果を確認して編集を調整し、引き続き作業できる XCF を保存できます。ヘッドレスモードでは、画像フォルダーに対して同じワークフローを実行します。

動作を見る

20秒の MP4 を見る · 編集可能な XCF を開く · MCP セッションを再現する

実際の GIMP ウィンドウを段階的に記録したウォークスルーで、待ち時間は短縮されています。MCP を通じて、1回のバッチ処理で3つのテキストレイヤーを変更します。Ctrl+Z を1回押すと3つすべてが元に戻り、Ctrl+Y で再適用されます。テキスト、アートワーク、背景は、それぞれ名前付きの別レイヤーに保たれます。これは実際のツール実行を示すものであり、すべてのモデルがプロンプトから同じ計画に従うという主張ではありません。

こんな依頼ができます

「このカードの見出しと補足テキストを変更してください。テキストレイヤーのままにして、編集を1回の取り消し操作にまとめ、書き出す前に結果を見せてください。」

「この透過アートワークを、白い縁取りと影のある Telegram スタンプにしてください。512 × 512 の PNG を保存してください。」

「同じサイズの PNG フレームをスプライトシートにまとめてください。XCF マスターを残し、アトラス JSON を書き出して、エクスポートしたピクセルが元画像と一致することを検証してください。」

付属のスキルは、レイヤー化されたアートワーク、スプライトシート、バッチジョブを案内します。ジョブを完了とする前に、実際の出力を確認して測定するようエージェントに指示します。

インストール

GIMP 3.2.x、Python 3.11+、uv と MCP クライアントが必要です。GIMP はサーバーと同じマシンにインストールしてください。ユーザープロファイルを作成するため、GIMP を一度起動してください。

uvx gimp-agent-mcp install-plugin
uvx gimp-agent-mcp install-skills
uvx gimp-agent-mcp doctor

ブリッジのインストールまたはアップグレード後に GIMP を再起動してください。開いている GIMP ウィンドウで、Filters → Development → Start Agent Bridge を選択します。

クライアントの MCP 設定に次の設定を追加してください。

{
  "mcpServers": {
    "gimp": {
      "command": "uvx",
      "args": ["gimp-agent-mcp", "serve"]
    }
  }
}

Claude Code の場合：

claude mcp add gimp -- uvx gimp-agent-mcp serve

Claude Code では、サーバーとスキルをプラグインとしてインストールすることもできます。スキルのインストールを参照してください。AI による背景削除を行うには、uvx --from "gimp-agent-mcp[segmentation]" gimp-agent-mcp serve でオプションのモデルランタイムをインストールしてください（MCP 設定でも同じ引数を使用します）。初回使用時にモデルがダウンロードされます。画像処理はローカルで行われます。

ソースから作業する場合は、uv sync --extra dev を実行してから、uv run gimp-agent-mcp install-plugin を実行してください。サーバーを uv run --no-sync --directory /absolute/path/to/repo gimp-agent-mcp serve として設定します。--no-sync を指定すると、別のサーバーが実行中の場合に Windows で実行ファイルがロックされるエラーを回避できます。

ウィンドウで作業するか、バッチを実行する

• 既存のウィンドウを使う場合： メニューからブリッジを起動します。同じドキュメントをそのまま手動で編集できます。
• ショートカットを使う場合： uvx gimp-agent-mcp shortcut を実行すると、ブリッジを有効にして GIMP を起動するランチャーが作成されます。
• エージェントから起動する場合： gimp_launch(mode="gui") は GIMP を開き、mode="headless" はウィンドウなしで実行します。

gimp_status と gimp_list_images は、GIMP のアクティブなユーザーディスプレイに関連付けられた画像、その選択中のレイヤー ID、選択範囲の境界、変更状態を報告します。ユーザーが「このレイヤー」や「選択範囲」と言った場合は、編集前にそのコンテキストを確認してください。特定のドキュメントには gimp_context(image_id) を使います。また、present=true を指定すると、そのドキュメントを前面に表示できます。複数のブリッジが実行されている場合、gimp_status は最新のブリッジファイルを参照します。ユーザーセッションがアクティブな間は、テスト用プロファイルを分離してください。

このツールが便利な理由

機能	得られるもの
視覚的なフィードバック	画像全体、レイヤー、領域のプレビュー、保存済みスナップショット、変更前後の比較、差分比較。診断用オーバーレイでは、座標グリッド、レイヤー枠、選択範囲の境界、ラベル付きの点を追加できます。元の画像は変更されません。
測定結果	ピクセルの色、アルファ境界、ヒストグラム、主要な色。スプライトのパッキングでは、エクスポートした PNG を再度開き、各セルのデコード済み RGBA ピクセルを元の画像と比較します。
編集可能な作業	名前付きレイヤー、テキスト、パス、マスク、非破壊のレイヤー効果。XCF のマスターと納品用ファイルは別々にエクスポートできます。
日常的な編集	3 つのコンパクトなツールで、一般的な調整、キャンバス変換、塗りつぶし、簡単な描画に対応します。各操作では、使用したインストール済みの GEGL または PDB の処理が報告されます。
1 回の取り消し	gimp_edit_batch は、対応する編集を 1 回の呼び出しにまとめます。gimp_undo_group は、終了するまで 1 つの画像に対する複数回の呼び出しをまたいだ編集をまとめるため、Ctrl+Z を 1 回押すだけでそのターンの編集を元に戻せます。ブリッジ接続が切断されると、グループは閉じられます。
実行時の検出	インストール済みの PDB プロシージャと GEGL 操作を検索して、パラメーター名、型、列挙値を含む詳細を確認できます。数値配列の引数は、カーブやブラシストロークに対応します。
繰り返し可能なジョブ	11 個のレシピとフォルダの一括処理に加え、3 つのワークフロースキルが同梱されています。
失敗時の誠実な処理	接続が切れた場合でも、結果が不明な編集が暗黙に再実行されることはありません。再接続して状態を確認してから、再試行するかどうかを判断してください。

ほかの GIMP MCP プロジェクトも、TCP ブリッジや視覚的なフィードバックを提供しています。このプロジェクトは、編集可能な出力、測定、編集のグループ化、再現可能な検証を重視しています。汎用 API による幅広いアクセスが可能ですが、すべての GIMP プロシージャや GEGL 操作が、あらゆる引数の組み合わせで動作するとは限りません。

ツール（40）

分野	ツール
学習と接続	gimp_help、gimp_status、gimp_launch、gimp_shutdown、gimp_context
画像	gimp_list_images、gimp_image_info、gimp_new_image、gimp_open、gimp_export、gimp_close_image
表示と測定	gimp_render、gimp_snapshot、gimp_drop_snapshot、gimp_render_compare、gimp_measure
PDB	gimp_pdb_search、gimp_pdb_describe、gimp_pdb_call
フィルター	gimp_filter_search、gimp_filter_describe、gimp_apply_filter、gimp_layer_effects、gimp_layer_effect
日常的な編集	gimp_adjust、gimp_canvas、gimp_draw
構造化編集	gimp_edit_batch、gimp_undo_group、gimp_select、gimp_layer_mask、gimp_layer、gimp_text、gimp_list_fonts、gimp_path
切り抜き	gimp_remove_background（オプションの rembg モデルランタイム）
自動化	gimp_run_python、gimp_list_recipes、gimp_run_recipe、gimp_batch_recipe、gimp_brand、gimp_cancel

画像とアイテムには整数 ID を使用します。色は 16 進数、一般的な色名、CSS RGB 文字列、またはコンポーネント配列で指定できます。列挙値には、describe ツールが返すニックネームを使用します。グループ編集の例は gimp_help("batch") を呼び出して確認してください。gimp_run_python が無効になっている場合、ツール数は 1 つ少なくなります。

一般的な作業で、手順を調べる必要はもうありません。たとえば、gimp_adjust(layer_id, "brightness_contrast", {"brightness": 0.15})、gimp_canvas(image_id, "crop", width=1200, height=630, x=40, y=20)、または gimp_draw(image_id, layer_id, "line", color="#ffffff", x=20, y=40, x2=300, y2=40, line_width=6) を使用します。GIMP が対応している場合、調整はデフォルトで編集可能なレイヤー効果になります。キャンバス操作と描画操作は、ピクセルまたは構造に直接反映されます。各結果には、実行前に選択されたランタイム操作が示されます。

視覚的な配置を行う場合は、作業中の画像にマークを付けずに診断用プレビューをリクエストしてください。

gimp_render(image_id=3, overlay=["grid", "layers", "selection"], grid_size=100,
            points=[{"x": 600, "y": 340, "label": "headline centre"}])

レシピ

レシピ	用途
telegram_sticker	透明な 512 × 512 キャンバスに合わせ、縁取りと影を追加します。
compose	画像、テキスト、図形、効果のマニフェストからカードやバナーを作成します。
sprite_sheet_pack	順序付けされた同サイズの PNG → 検証済みのグリッド PNG、レイヤー付き XCF、アトラス JSON を生成します。マージンと間隔はオプションです。
sprite_atlas_pack	サイズの異なる PNG → パディングを追加し、オプションでトリミングしたアトラス PNG、レイヤー付き XCF、アトラス JSON を生成し、ピクセル単位で検証します。
social_crop	焦点に合わせて指定のソーシャルプロフィール（Open Graph、X、Instagram、ストーリー、YouTube、またはカスタム）用にトリミングし、出力を測定してピクセル単位でチェックします。
sprite_sheet_slice	シートから固定サイズのタイルを切り出します。空のセルはオプションでスキップできます。
web_optimise	ファイルサイズの上限を目標に、サイズ変更とエクスポート品質の調整を行います。
icon_set	正方形のソース画像を複数のサイズでエクスポートします。
watermark	テキストまたは画像のウォーターマークを配置します。
contact_sheet	フォルダー内のサムネイルにラベルを付けて一覧にします。
fit_and_export	最大辺に合わせてから、拡張子に応じた形式でエクスポートします。

compose 用ブランドキット

ブランドの色、フォント、アセット、キャンバスサイズを一度保存すれば、以降はトークンで参照できます。プロフィールはユーザーごとの設定ディレクトリ内の JSON ファイルです（Windows では %APPDATA%\gimp-agent-mcp\brands、macOS では ~/Library/Application Support/gimp-agent-mcp/brands、それ以外では $XDG_CONFIG_HOME/gimp-agent-mcp/brands。GIMP_AGENT_BRANDS_DIR で上書きできます）。プロフィールを保存する際、フォント名は実行中の GIMP に照らして確認されます。

gimp_brand(action="set", profile={"name": "example",
  "colors": {"bg": "#0f1117", "accent": "#1f3a8a", "text": "#ffffff"},
  "fonts": {"headline": "Bahnschrift Bold"}, "assets": {"logo": "/brand/logo.png"},
  "canvases": {"x-card": [1200, 675], "og": [1200, 630]}})

gimp_run_recipe("compose", {"output_path": "out/card.png", "manifest": {
  "brand": "example", "canvas": "x-card", "background": "@bg",
  "items": [{"type": "image", "path": "@logo", "x": 40, "y": 40, "width": 160},
            {"type": "text", "text": "Launch day", "font": "@headline", "size": 72, "color": "@text", "x": 40, "y": 240}]}})

GIMP に渡す前にサーバー側でトークンが解決されるため、トークンを使ったマニフェストは、手作業で記述した場合とまったく同じマニフェストになります。リテラル値も引き続き使用でき、プロフィールの値より優先されます。不明なトークンを指定すると、プロフィール名と利用可能なキーが示されてエラーになります。詳細なルールは gimp_help("compose") で確認できます。

レシピの引数と例 · アセットのワークフロー · スキル

テスト済みの範囲と制限事項

バージョン 0.5.0、ベータ版です。Windows GIMP 3.2.4、Linux GIMP 3.2.2（Ubuntu 26.04）、および Apple Silicon と Intel 搭載の macOS 15 GIMP 3.2.4 でテスト済みです。各プラットフォームで、実際の GIMP を使用してスモークテスト一式、対象機能の検証、および日常的な編集操作 23 件すべてを実行します。GIMP 2.10 はサポート対象外です。以前の 3.x リリースは現在のテストマトリックスに含まれていません。

• gimp_edit_batch は、レイヤー、テキスト、選択範囲、パス、マスク、フィルターに対する範囲を限定した編集を受け付けます。gimp_undo_group(image_id, action="start", name="agent: sticker pass") は複数の呼び出しにわたってグループを維持します。終了するには action="end" を指定します。gimp_status は開いているグループを一覧表示します。クライアントが切断されると、そのクライアントのグループは閉じられます。指定した名前はブリッジによって追跡されますが、GIMP 3 の公開 Undo グループ API では Undo History のラベルを設定できません。ユーザーは GIMP の「元に戻す」／「やり直し」を使用します。プログラムから元に戻すエンドポイントはありません。
• uv run python scripts/undo_group_smoke.py は、GUI の GIMP セッションで Ctrl+Z を一度押した後、ターン開始前のスナップショットと照合して 3 件の編集を確認します。ヘッドレスの gimp-agent-mcp smoke チェックでは、グループのライフサイクルと切断時のクリーンアップを確認します。
• 線形グラデーションなど、一部の GEGL ソース操作は描画可能なフィルターではありません。代わりに PDB のグラデーション塗りつぶし手順を使用してください。ベクターのワープ／ゆがみ機能との同等性は保証していません。詳しくはワープ調査ノートを参照してください。
• スプライトのパッキングでは、同じサイズのフレーム（余白と間隔を指定する sprite_sheet_pack）またはサイズが混在する PNG と開いているレイヤー（パディングとトリミングを指定する sprite_atlas_pack）を扱います。どちらもアニメーションに合わせた配置やスプライトの回転には対応していません。
• 時間のかかる処理では進捗が報告され、チェックポイントで gimp_cancel を使ってキャンセルできます。対象となるのは、レシピ項目間、バッチファイル間、編集バッチの各ステップ間、checkpoint() を呼び出す gimp_run_python コードの各パス間、およびフィルターの開始前です。実行中の GEGL マージ処理 1 件は中断できません。また、GIMP 独自のプロシージャ単位の進捗はまだ転送されません。

セットアップを確認する

uvx gimp-agent-mcp smoke
# From the source checkout:
uv run pytest
uv run python scripts/capability_proof.py /path/to/proof-output
uv run python scripts/everyday_proof.py /path/to/proof-output

CI ではサポート対象の Python バージョンを確認し、別々のジョブで Windows、Linux、macOS の両アーキテクチャ上の実際の GIMP をテストします。リリースの公開には、実際の GIMP を使う 3 つすべてのワークフローの成功が必要です。一般的な機能検証では、カーブ、グラデーション、ブラシの出力を測定し、バッチ処理からの復旧、ドキュメント境界、診断オーバーレイ、ネストされたプレビュー、スナップショットのクリーンアップを確認します。2 つ目の検証では、gimp_adjust、gimp_canvas、gimp_draw の各アクションをすべて解決して実行し、寸法、レイヤー数、測定したピクセルを記録します。検証の詳細を参照してください。

各スモークテストと検証スクリプトは、自ら起動した GIMP 上で実行されます。その GIMP を終了する際は、ブリッジが実際に停止する（ポートが閉じ、ブリッジファイルが削除され、プラグインプロセスが終了する）まで待ってから戻ります。終了を指示されたブリッジは、新しい接続と新しいリクエストをただちに拒否します。スモークテストでは shutdown (bridge gone before return) チェックでこれをアサートします。また CI では GIMP_AGENT_REQUIRE_OWN_GIMP=1 を設定し、以前の手順で起動したブリッジがまだ応答していることを検証で検出した場合、それを借用せず、その理由を示して失敗するようにしています。これにより、2026 年 10 月 15 日に発生した macOS arm64 のライブスモークテスト失敗が解決しました。GIMP のクラッシュに見えていましたが、実際には終了中の前の手順の GIMP に検証が接続していました。ライブジョブではチェックを再試行しません。macOS のジョブが失敗した場合、そのログには macOS が GIMP のクラッシュレポートを書き出したかどうかが記録されます。また、macos-gimp-proof-<arch> アーティファクトには、検証レポート、GIMP の起動ログ、およびクラッシュレポートがある場合はそのレポートが含まれます。

アーキテクチャと信頼性

MCP client → stdio server → authenticated loopback TCP → plug-in inside GIMP

プラグインはワーカースレッドを使わず、GLib メインループ上で処理を実行します。インストールごとのトークンを使用し、127.0.0.1 のみにバインドします。PDB 呼び出し、レシピ、Python はユーザー権限でコードを実行できます。信頼できるクライアントのみ接続してください。gimp_run_python を無効にしても、サンドボックスにはなりません。セキュリティ · アーキテクチャ

Apache-2.0 ライセンスに基づくクリーンルーム実装です。他の GIMP MCP プロジェクトからコードをコピーしていません。ロードマップ · 変更履歴 · バグを報告