GIMP 3 MCP

gimp3-mcp

gimp3-mcp を使うと、AI アシスタントが起動中の GIMP 3.2 を操作できます。希望する内容を伝えると、アシスタントが画像を作成または開き、描画や編集、エクスポートを行い、各ステップの間に画像を確認して作業をチェックします。

構成は2つです。GIMP 内で動作する GIMP プラグインと、AI クライアント（Claude Desktop、Claude Code、その他の MCP クライアント）が起動するMCP サーバーです。これらが連携し、ブラシストロークや色調整から、レイヤー、テキスト、一括エクスポートまで、80種類のツールをアシスタントに提供します。

gimp3-mcp は、maorcc とコントリビューターによる gimp-mcp のフォークとして始まり、現在は独立して開発されています。クレジットとgimp-mcp との違いをご覧ください。

---

依頼できること

各例はアシスタントに伝えるプロンプトと、通常アシスタントが使用するツールです。

絵を描く

Create an 800×800 canvas and paint a ginger cat sitting front-on, in loose painterly strokes.
Look at the canvas after each round of strokes.

new_canvas → ラウンドごとに paint_stroke（テクスチャブラシ、先細りのストローク、ぼかし） → get_state_snapshot または preview オプションで確認 → sample_color でキャンバス上の色を取得します。

写真をレタッチする

Open ~/Pictures/harbor.jpg, auto-level it, add a little contrast and warmth,
sharpen slightly, and export a 2048-pixel-wide JPEG to ~/Pictures/harbor-edit.jpg.

open_image → auto_levels → adjust_brightness_contrast → adjust_color_balance → sharpen → scale_to_fit → export_image。

グラフィックを作成する

Make a 1200×630 banner with a dark navy background (#1b2a4a) and the title "Summer Sale"
in large white text with a soft drop shadow, then export it for the web.

new_canvas → add_text → apply_drop_shadow → export_web_optimized。

詳細を調べる

Show me the top-left 300×300 pixels of the current image, enlarged.

region を指定して get_state_snapshot を呼び出します。

多数の画像を扱う

Export every open image as WebP into ~/Desktop/export.

list_images → batch_export。

ツールで対応できないこと

Use GIMP's Python API to list every path in the image and how many strokes each has.

call_api は GIMP 内で Python を実行します。

ツール呼び出しの例

これらの呼び出しはアシスタントが記述するため、あなたが記述する必要はありません。ただし、ツールが受け付ける内容を示しています。各ブロックは、指定されたツールに渡す引数です。

get_state_snapshot：画像の一部を確認します（座標は画像のピクセル単位です。結果は max_size に収まるように拡大縮小されます）。

{"image_index": 0, "max_size": 512,
 "region": {"x": 140, "y": 80, "width": 240, "height": 300}}

paint_stroke：ストロークをひとまとまり描画し、プレビューを取得します。

{"preview": true, "strokes": [
  {"points": [[100, 400], [300, 330], [520, 380]], "brush": "Oils 01", "size": 120, "color": "#3b6e8f"},
  {"points": [[140, 420], [300, 370]], "brush": "Bristles 02", "size": 40, "color": "#d9a441", "opacity": 80},
  {"points": [[250, 360], [330, 350]], "tool": "smudge", "size": 50, "pressure": "none", "strength": 40}
]}

call_api：GIMP 内で Python を評価します。

{"api_path": "exec", "args": ["pyGObject-eval", ["len(Gimp.get_images())"]]}

---

仕組み

AI client (Claude Desktop, Claude Code, ...)
      │  MCP over stdio
      ▼
gimp_mcp_server.py        MCP server: tool definitions and descriptions
      │  JSON over TCP, localhost:9877
      ▼
gimp-mcp-plugin.py        GIMP plugin: runs inside GIMP
      │  PyGObject
      ▼
GIMP 3.2

クライアントが MCP サーバーを起動します。サーバーは各ツール呼び出しを JSON コマンドに変換してプラグインに送信し、プラグインは GIMP の Python API を使って実行して結果を返します。プラグインは一度に1つのコマンドを実行します。

---

必要条件

• GIMP 3.2（macOS で 3.2.6 を使って開発・テストしています）
• uv（uvx を提供し、必要に応じて Python 3.11 以降を取得します）
• MCP クライアント（Claude Desktop や Claude Code など）

---

インストール

1. GIMP プラグインをインストールする

GIMP を一度起動して設定フォルダーを作成してから、次を実行します。

uvx gimp3-mcp install-plugin

これにより、プラグインが GIMP の設定フォルダー内の plug-ins/gimp-mcp-plugin/ にコピーされ、後で AI クライアントがすばやく起動できるようサーバーがダウンロードされます。この処理では、macOS では ~/Library/Application Support/GIMP、Windows では %APPDATA%\GIMP、Linux では ~/.config/GIMP、~/snap/gimp/current/.config/GIMP、~/.var/app/org.gimp.GIMP/config/GIMP を検索し、見つかった中で最も新しい GIMP 3.x のフォルダーを使用します。GIMP の設定フォルダーが別の場所にある場合は、--gimp-dir を指定してください。GIMP が使用しているフォルダーは、編集 > 設定 > フォルダー > プラグインで確認できます。GIMP はマイナーバージョンごとに新しい設定フォルダーを作成するため、GIMP をアップグレードした後はコマンドを再度実行してください。インストール後、GIMP を再起動します。

2. GIMP でプラグインのサーバーを起動する

ツール > MCP > MCP サーバーを起動を選択します。画像を開いておく必要はありません。サーバーは GIMP を終了するまで localhost:9877 で待ち受けるため、GIMP を起動するたびに再度起動してください。同じメニューにMCP サーバーを確認とMCP サーバーを再起動もあります。

3. AI クライアントを接続する

Claude Desktop。 サーバーを claude_desktop_config.json に追加します。このファイルは、macOS では ~/Library/Application Support/Claude/ に、Windows では %APPDATA%\Claude\ にあります。

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

Claude Desktop を終了して、再度開きます。Claude Desktop では、コネクターのツールを個別に有効または無効にできます。アシスタントが new_canvas などのツールを使用できないと伝えた場合は、gimp コネクターのツール設定でそのツールを有効にして、新しいチャットを開始してください。

Claude Code。

claude mcp add --scope user gimp -- uvx gimp3-mcp

その他の MCP クライアント。 uvx コマンドと gimp3-mcp 引数を使って、stdio サーバーを設定します。

4. 接続を確認する

アシスタントに「GIMP の接続を確認して」と依頼します。アシスタントは check_server を呼び出し、プラグインに接続できるかどうかと、実行中の GIMP のバージョンを報告します。

---

ツール

このサーバーは 80 個のツールを提供します。各ツールの説明には、アシスタントが確認するパラメーターと結果が記載されています。

画像の表示

ツール	機能
get_state_snapshot	画像または領域を、max_size に収まるように拡大縮小した PNG で取得します。アシスタントが画像を見る主な方法です
get_image_bitmap	同じ画像データを取得します。max_width／max_height と origin_x／origin_y の領域キーを個別に指定できます
get_image_metadata	サイズ、カラーモード、解像度、レイヤー、ファイル
sample_color	表示中の画像上の点の色を 16 進数で取得します。オプションで半径内の平均色を取得できます
get_pixel_color	表示中の画像または単一レイヤー上の 1 ピクセルの色を取得します
get_histogram	レイヤーのチャンネルの平均値、中央値、ばらつき
get_selection_bounds	現在の選択範囲の境界ボックス
list_images	開いている画像をインデックス順に、名前とサイズとともに一覧表示します
list_layers	レイヤーを上から順に一覧表示し、アクティブなレイヤーを示します

画像とファイル

ツール	機能
new_canvas	新しいウィンドウに空の画像を作成します
open_image	新しいウィンドウで画像ファイルを開きます
save_xcf	レイヤーを保持したまま、GIMP の XCF 形式で保存します
export_image	PNG、JPEG、WebP、または TIFF にエクスポートします
close_image	new_canvas または open_image で開いた画像を閉じます（必要に応じて、先に XCF として保存します）
set_active_image	画像のウィンドウを前面に表示します
convert_color_mode	RGB、グレースケール、またはインデックスカラーに変換します

ペイントと描画

ツール	機能
paint_stroke	テクスチャブラシ、先細りまたは筆圧を変化させたストローク、エアブラシ、ぼかし、消しゴムなどのブラシストロークをまとめて描画します
list_brushes	paint_stroke で使用できるブラシ名
draw_line	鉛筆またはペイントブラシで直線を描画します
draw_rectangle / draw_ellipse	矩形または楕円の輪郭を描画します
fill_rectangle / fill_ellipse	矩形または楕円を塗りつぶします
fill_layer	レイヤー全体を色で塗りつぶします
fill_selection	選択範囲を、色、GIMP の描画色または背景色、パターン、あるいは透明色で塗りつぶします
gradient_fill	線形または放射状のグラデーション
set_colors	GIMP の描画色と背景色を設定します

調整

ツール	機能
adjust_brightness_contrast	明るさとコントラスト
adjust_curves	チャンネルごとのカーブ。プリセットまたはカスタムポイントを使用できます
adjust_hue_saturation	すべての色または単一の色域の色相、彩度、明度
adjust_color_balance	シャドウ、中間調、ハイライトのカラーバランス
auto_levels	色調の範囲を自動的に引き伸ばします
desaturate	レイヤーをグレースケールに変換します
invert_colors	レイヤーの色を反転します

フィルターとエフェクト

ツール	説明
blur / apply_gaussian_blur	ガウスぼかし（blur では水平方向と垂直方向の半径を個別に指定します）
sharpen	アンシャープマスク
denoise	ノイズ除去
apply_noise	ノイズまたは粒状感を追加
apply_pixelate	ブロック状のモザイク
apply_emboss	エンボス
apply_vignette	端を暗くする
apply_drop_shadow	レイヤーの下に柔らかいドロップシャドウを追加
warp_region	無効：GIMP 3.2 ではワープではなくレイヤーが消去されたため、現在はエラーを返します

変形

ツール	説明
scale_image	正確なサイズに拡大・縮小
scale_to_fit	アスペクト比を維持して、指定範囲に収まるよう拡大・縮小
crop_to_rect	矩形に切り抜く
crop_to_selection	選択範囲に切り抜く、または自動で切り抜く
rotate_image	90、180、270 度、または任意の角度で回転
flip_image	水平方向または垂直方向に反転
resize_canvas	コンテンツを拡大・縮小せずにキャンバスサイズを変更

選択範囲

ツール	説明
select_rectangle / select_ellipse	矩形または楕円の選択範囲を作成し、必要に応じてぼかしを適用
select_by_color	色が近いピクセルを選択
select_all / select_none	すべてを選択、または選択を解除
invert_selection	選択範囲を反転
modify_selection	選択範囲を拡張、縮小、ぼかし、境界線化、またはシャープ化

レイヤー

ツール	説明
create_layer	空または塗りつぶし済みの新しいレイヤーを作成
duplicate_layer	レイヤーを複製
delete_layer	レイヤーを削除
rename_layer	レイヤー名を変更
reorder_layer	レイヤースタック内でレイヤーを移動
set_layer_properties	不透明度、合成モード、表示状態を設定
merge_visible_layers	表示レイヤーを結合
flatten_image	すべてのレイヤーを統合

テキスト

ツール	説明
add_text	テキストレイヤーを追加
edit_text	テキストレイヤーのテキスト、フォント、サイズ、色を変更
list_fonts	インストール済みフォントを名前で絞り込んで一覧表示

バッチ処理とエクスポートのパイプライン

ツール	説明
batch_export	開いているすべての画像、または指定した画像をフォルダーにエクスポート
batch_resize	開いているすべての画像のサイズを変更
export_web_optimized	JPEG と PNG をエクスポートし、どちらのファイルサイズが小さいかを報告
export_social_media_kit	Instagram、Twitter/X、Facebook、YouTube 用のサイズでエクスポート
export_icon_sizes	Android または iOS 用のアイコンセットをエクスポート
export_sprite_sheet	レイヤーまたは開いている画像をスプライトシートにまとめる

接続と詳細設定

ツール	説明
check_server	プラグインに接続できることを確認
restart_server	GIMP の再起動後に再接続
get_gimp_info	GIMP のバージョン、フォルダー、環境情報を取得
get_context_state	GIMP の現在の色、ブラシ、不透明度、モードを取得
call_api	ツールでは対応できない操作のために、GIMP 内で Python を実行

サーバーは gimp_best_practices と gimp_iterative_workflow の 2 つの MCP プロンプトも提供します。プロンプトに対応するクライアントは、これらを会話に追加できます。プロンプトは docs/best_practices.md と docs/iterative_workflow.md にもあります。

---

ツールの動作

アシスタントは接続時にこれらのルールを受け取ります。ツール呼び出しを確認したり、結果をデバッグしたりするときにも役立ちます。

• 画像の順序。 image_index 0 は、直近に開いた画像または作成した画像です。画像を開いたり閉じたりすると、インデックスは変わります。list_images で現在の順序を確認できます。
• レイヤー。 layer_name が任意のツールは、アクティブなレイヤーを操作します。create_layer または duplicate_layer で作成したレイヤーはアクティブになります。list_layers では、インデックス 0 が最上位のレイヤーです。
• 色。 色は16進数（"#8b4513"、"#fff"、"#8b451380"）または16種類の基本CSSカラー名（black、white、gray、silver、red、maroon、yellow、olive、lime、green、aqua、teal、blue、navy、fuchsia、purple）で指定します。その他の名前と rgb() 値は拒否されます。GIMPが誤った色に変換するためです。
• スナップショット。 get_state_snapshot は、画像または領域を max_size に収まるように拡大・縮小するため、小さな領域は拡大して返されます。領域の座標は画像のピクセル単位です。
• 推測せずエラーを返します。 ブレンドモード、補間方法、アンカーなど、値が固定リストから選ばれるオプションは、リストにない値を拒否し、エラーに有効な値を示します。GIMPがフィルターを適用できない場合も、エラーを返します。
• 画像を閉じる。 close_image では、new_canvas または open_image で開いた画像を閉じられます。GIMP 3では、プラグインからGIMPのメニューで開いたウィンドウを閉じる方法はありません。その場合はGIMPで閉じてください。
• 元に戻す。 GIMP 3ではプラグインが元に戻す履歴をたどれないため、元に戻すツールはありません。paint_stroke の各バッチを含む各ツール呼び出しは、GIMPでCtrl+Zを押すと元に戻せる1つの手順です。アシスタントが作業を破棄できるようにするには、別のレイヤーに描画させ、そのレイヤーを削除してください。

---

セキュリティ

このプラグインは、call_api を通じて受け取ったPythonコードを実行します。サーバーの起動中は、localhost:9877 に接続できるコンピューター上のプログラムであれば、GIMPを操作し、ユーザーの権限でコードを実行できます。プラグインはお使いのコンピューターからの接続のみを受け付けます。使用するときにサーバーを起動し、停止するにはGIMPを終了してください。

---

スクリプトの例

これらのスクリプトは、AIクライアントを介さずにプラグインと直接やり取りします。まずGIMPでプラグインのサーバーを起動してください。使い方は各ファイルの冒頭に記載されています。

スクリプト	説明
bg_remove.py	ファジー選択を1回実行して背景を削除します
bg_remove_iterative.py	スナップショットを確認しながら、背景を繰り返し削除します
agent_edit_demo.py	画像を開き、背景を削除し、口をゆがませて笑顔にし、スナップショットを確認して、エクスポートします（warp_region が無効な間は、ゆがませる処理に失敗します）

---

トラブルシューティング

「GIMP に接続できませんでした」

• GIMP を起動し、ツール > MCP > MCP サーバーを起動を選択します。GIMP を再起動するたびに、もう一度この操作が必要です。
• AI クライアントを起動したまま GIMP を再起動した場合は、アシスタントに restart_server を実行するよう依頼します。

GIMP に MCP メニューが表示されない

• ツール > MCPを確認します。
• uvx gimp3-mcp install-plugin をもう一度実行し、GIMP を再起動します。プラグインは、現在の GIMP バージョンの設定フォルダー（編集 > 設定 > フォルダー > プラグイン）内の plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py に配置する必要があります。また、GIMP はマイナーアップグレードのたびに新しいフォルダーを使用します。
• macOS と Linux では、ファイルが実行可能であることを確認して（chmod +x）、GIMP を再起動します。
• プラグインのエラーは、GIMP のウィンドウ > ドッキング可能なダイアログ > エラーコンソールに表示されます。

アシスタントからツールが存在しないと言われる

• gimp3-mcp を更新した後、AI クライアントを再起動します。
• Claude Desktop では、gimp コネクターのツール設定でツールが有効になっていることを確認します。

クライアントがサーバーを起動できない、または uvx が見つからないと言う

• デスクトップから起動したアプリでは、シェルの PATH が認識されないことがあります。ターミナルで which uvx を実行し、たとえば "command": "/usr/local/bin/uvx" のように、設定にそのフルパスを指定します。
• 初回起動時にパッケージがダウンロードされます。クライアントがタイムアウトする場合は、ターミナルで uvx gimp3-mcp install-plugin を一度実行してキャッシュを作成し、もう一度試します。

プラグインを変更しても反映されない

• GIMP は起動時にプラグインを読み込みます。gimp3-mcp を更新した後、uvx gimp3-mcp@latest install-plugin を実行し、GIMP を再起動してからサーバーを起動します。uvx はキャッシュされたコピーを使用するため、@latest を付けると最新リリースを取得できます。

---

開発

開発用の依存関係と、各コミットで ruff を実行する pre-commit フックをインストールします。

uv sync
uv run pre-commit install

CI と同じリントチェックを実行します（バージョンは .github/workflows/lint.yml と .pre-commit-config.yaml で固定されています）。

uvx [email protected] check .

テストは実行中の GIMP と通信するため、先にプラグインのサーバーを起動してください。テストはそれぞれ独自の画像を作成または開きますが、run_tests.py は最後に開いた画像を編集するため、実行前に作業内容を保存してください。

python run_tests.py                   # 85 checks across the tool categories
python tests/test_paint_stroke.py     # paint_stroke, list_brushes, sample_color
python tests/test_add_text_metadata.py

run_tests.py は GIMP の前景色と背景色を変更し、テスト用キャンバスを開いたままにします。tests/continuous_edit_test/continuous_edit_test.py は開いている画像をすべて閉じるため、残しておきたい作業があるセッションでは実行しないでください。

PyPI ではなくチェックアウトから実行するには：

git clone https://github.com/tifyr/gimp3-mcp.git
cd gimp3-mcp
uv sync
uv run gimp3-mcp install-plugin

次に、クライアントでコマンドに uv を指定し、引数として run --directory /full/path/to/gimp3-mcp gimp_mcp_server.py を指定します。このフォルダーで起動した Claude Code では、.mcp.json に同じサーバーが用意されています。gimp-mcp-plugin.py を変更した後は、uv run gimp3-mcp install-plugin を実行して GIMP を再起動します。gimp_mcp_server.py を変更した後は、AI クライアントを再起動します。

リリースするには、pyproject.toml と server.json の両方の箇所に新しいバージョンを設定し、CHANGELOG.md に内容を記載して、v0.2.0 のようなタグをプッシュします。Release ワークフローでバージョンが一致していることを確認した後、PyPI と MCP Registry に公開します。

---

gimp-mcp との違い

gimp3-mcp は、GIMP プラグインと MCP サーバーを組み合わせた gimp-mcp の設計と、ツールの大半を引き継いでいます。フォーク後に、次の機能が追加されました。

• ペイントツール： GIMP 標準のブラシで描画するための paint_stroke、list_brushes、sample_color。
• macOS で GIMP がフリーズする問題を修正： プラグインは一度に 1 つのコマンドを実行します。
• 失敗を隠しません： auto_levels や gradient_fill のように何もせず成功を報告していたツールが動作するようになり、GIMP の呼び出しが失敗した場合はエラーを返します。
• 作業内容を失いません： resize_canvas はレイヤーを保持し、close_image が別のファイルを上書きすることはありません。ツールは GIMP の色や選択範囲を変更せず、レイヤーを消去していた warp_region は無効になっています。
• サーバーの信頼性が向上： 返信が失われたり、GIMP の呼び出しに時間がかかった際にすべてのリクエストが停止したりすることがなくなりました。
• 結果を検証するテスト： run_tests.py は、ツールが報告するステータスだけでなく、ピクセル、色、選択範囲も確認します。
• PyPI からインストール可能： uvx gimp3-mcp を実行すると、プラグインをインストールするコマンドが利用できます。

詳細は CHANGELOG.md をご覧ください。

---

制限事項

• GIMP が起動し、MCP サーバーが開始されている必要があります（Tools > MCP > Start MCP Server）。gimp3-mcp が GIMP を起動することはできません。
• macOS 上の GIMP 3.2.6 で開発とテストを行っています。Linux と Windows でも動作するはずですが、このリリースではテストされていません。
• GIMP 3.2 ではプラグインが利用できる動作するワープ操作がないため、warp_region は無効になっています。
• プラグインは一度に 1 つのコマンドを実行するため、時間のかかる操作によって次の呼び出しが待たされます。
• call_api は GIMP 内で任意の Python コードを実行します。セキュリティをご覧ください。

---

クレジット

gimp3-mcp は、maorcc が作成し、tomer、jmagdalena、Victor（Viesar Lab）、AnthonyHerman ほかが貢献した gimp-mcp をベースにしています。プラグイン、サーバー、ツールの大半は彼らの成果であり、彼らのコミットはこのリポジトリの履歴に保持されています。gimp3-mcp は tifyr が独立してメンテナンスしており、gimp-mcp の公式リリースではありません。

---

ライセンス

gimp-mcp と同じ GPL-3.0 ライセンスです。LICENSEをご覧ください。