Gimp Mcp Server

GIMP MCP

デモ

デモ全編（音声付き）：https://github.com/maorcc/gimp-mcp/raw/main/docs/demo.mp4

Claude経由の自然言語で、AI エージェントがGIMP MCPを使って背景を削除し、キャラクターの表情を編集し、結果を確認します

---

概要

GIMP MCPは、Model Context Protocolを通じて、GIMPのプロフェッショナルな画像編集機能とAI アシスタントを連携させます。実現したいことを説明するだけで画像を編集でき、AIには変更を進める前に一つひとつ確認するための、リアルタイムな視覚フィードバックチャネルが提供されます。

他のGIMP連携と異なる点：

• ワークフローのどの時点でも、ディスクに保存せずにAIが画像を確認できます（get_state_snapshot）
• 完全自律型の複数ステップのパイプラインに対応：開く → 編集 → 確認 → 調整 → エクスポート
• GIMPの主要な操作を網羅する56個の専用ツールコマンド
• GIMP 3.2.xに完全対応（互換性を損なうAPI変更はすべて解決済み）

主な機能

👁️ リアルタイムの視覚フィードバック	get_state_snapshotはワークフローの途中でPNGプレビューを返し、AIが各ステップを確認できます
🎨 56個のGIMPツール	調整、変形、選択、レイヤー、描画、テキスト、フィルターなど、すべてMCP経由で操作できます
🔧 GIMP 3.2対応	GIMP 3.2のAPI変更をすべて修正し、テスト済みです（56/56件合格）
🔁 反復型ワークフロー	AIは目標を達成するまで処理を繰り返します — たとえば、ピクセルが残らなくなるまで背景を削除し続けます
🖼️ 領域スナップショット	任意の領域を拡大して詳細を確認できます（顔、口、角など）
🔌 幅広いMCP対応	Claude Desktop、Claude Code、Gemini CLI、PydanticAIなどで利用できます

何ができますか？

反復確認による背景の削除

AIが背景を削除し、スナップショットを撮って結果を確認します。残っているピクセルを検出し、画像がきれいになるまで処理を繰り返します：

"Remove the background from this image and keep looping until only the character remains"

表情の編集

"Make the character smile — paint a smile arc with teeth over her mouth"

複雑な複数ステップのパイプライン

"Open navi_portrait.png, remove the background, verify it's clean,
 then make her smile and export the final result as a PNG"

色とトーンの調整

"Boost the contrast, shift the hue 15 degrees warmer, then show me a before/after zoom of the face"

テキストと合成

"Add a bold title at the top in white with a subtle drop shadow, then export for web"

---

前提条件

• GIMP 3.2+ — GIMP 3.2.2でテスト済み（Windows、macOS、Linux）
• Python 3.8+ — MCP サーバー用
• uv — Pythonパッケージマネージャー（pip install uv）
• MCP対応AIクライアント — Claude Desktop、Claude Code、Gemini CLI、PydanticAIなど

---

クイックスタート

1. 依存関係をインストールする

git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp
uv sync

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

gimp-mcp-plugin.pyをGIMPのプラグインディレクトリにコピーし、GIMPを再起動します。

ディレクトリはどこですか？ GIMPはユーザーごとのフォルダーにメジャー.マイナーバージョン（ 3.0、3.2、3.4など）の名前を付け、マイナーアップグレードのたびに新しいフォルダーを作成するため、GIMPのアップグレード時にフォルダーが 移動します（例：3.0 → 3.2）。以下のスニペットは最新のフォルダーを自動選択するため、アップグレード後もそのまま動作します。パスを手動で確認するには、GIMPを開き、 編集 → 設定 → フォルダー → プラグインを確認してください。

実行前にGIMPを少なくとも一度起動し、設定フォルダーが作成されていることを確認してください。

macOS / Linux：

# Pick the base directory for your platform:
BASE="$HOME/Library/Application Support/GIMP"     # macOS
# BASE="$HOME/.config/GIMP"                        # Linux (standard)
# BASE="$HOME/snap/gimp/current/.config/GIMP"      # Linux (Snap)

# Auto-select the newest GIMP 3.x config directory (3.0, 3.2, 3.4, ...):
GIMP_DIR="$(ls -d "$BASE"/3.* 2>/dev/null | sort -V | tail -1)"
if [ -z "$GIMP_DIR" ]; then
  echo "No GIMP 3.x config dir found under $BASE — launch GIMP once, then re-run." >&2
  exit 1
fi
mkdir -p "$GIMP_DIR/plug-ins/gimp-mcp-plugin"
cp gimp-mcp-plugin.py "$GIMP_DIR/plug-ins/gimp-mcp-plugin/"
chmod +x "$GIMP_DIR/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py"
echo "Installed into: $GIMP_DIR/plug-ins/gimp-mcp-plugin"

Windows：

%APPDATA%\GIMP\<VERSION>\plug-ins\gimp-mcp-plugin\gimp-mcp-plugin.py

<VERSION>をGIMPのメジャー.マイナーバージョン（例：3.2）に置き換えます。Windowsではchmodは不要です。コピーしてGIMPを再起動してください。

すべてのプラットフォーム向け：GIMPプラグインのインストールガイド

3. GIMPでMCP サーバーを起動する

1. GIMPで任意の画像を開きます
2. ツール > MCP > MCP サーバーを起動を選択します
3. サーバーはlocalhost:9877で起動します

4. MCP クライアントを設定する

Claude Desktop

~/.config/Claude/claude_desktop_config.json（Linux/macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

Claude Code

cd /path/to/gimp-mcp
claude  # .mcp.json is auto-detected

または、手動で設定します：

claude mcp add gimp-mcp -- uv run --directory /full/path/to/gimp-mcp gimp_mcp_server.py

Gemini CLI

~/.config/gemini/.gemini_config.json：

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

PydanticAI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio('uv', args=['run', '--directory', '/path/to/gimp-mcp', 'gimp_mcp_server.py'])
agent = Agent('openai:gpt-4o', mcp_servers=[server])

---

利用可能な MCP ツール

👁️ 視覚的なフィードバック

get_state_snapshot(image_index, max_size, region, label)

現在の画像の状態を PNG 形式でリアルタイムに返します。AI の主なフィードバック手段です。ディスクに保存せずに結果を確認できるよう、編集の合間に呼び出してください。

# Full image snapshot
snapshot = get_state_snapshot(max_size=512)

# Zoom into a face region for detail inspection
snapshot = get_state_snapshot(
    region={"x": 140, "y": 80, "width": 240, "height": 300},
    max_size=512,
    label="face-check"
)

これにより、反復的なエージェント型ワークフローが可能になります：編集 → スナップショット → 評価 → 改良 → 繰り返し。

get_image_bitmap(image_index, max_width, max_height, region)

領域の抽出と拡大縮小に対応した、より低レベルのビットマップ取得機能です。Base64 エンコードされた PNG を返します。

🎨 調整

ツール	説明
adjust_brightness_contrast	明るさとコントラスト
adjust_curves	チャンネル別のカーブ（RGB/R/G/B/A）
adjust_hue_saturation	色相、彩度、明度
adjust_color_balance	シャドウ／中間調／ハイライトのカラーバランス
auto_levels	レベルを自動調整
desaturate	グレースケールに変換（RGB モードを維持）
invert_colors	すべてのチャンネルを反転
sharpen	アンシャープマスクによるシャープ化
blur	ガウスぼかし
denoise	ノイズ除去

🔄 変形

ツール	説明
scale_image	指定した正確な寸法に拡大縮小
scale_to_fit	バウンディングボックス内に収まるよう拡大縮小（縦横比を維持）
crop_to_rect	矩形に切り抜き
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	レイヤー名を変更
set_layer_properties	不透明度、合成モード、表示状態
reorder_layer	レイヤーの重ね順を変更
merge_visible_layers	表示レイヤーを1つに統合
flatten_image	すべてのレイヤーを統合
list_layers	すべてのレイヤーとプロパティを一覧表示

🖌️ 描画と塗りつぶし

ツール	説明
fill_layer	レイヤー全体を色で塗りつぶし
fill_selection	選択範囲を塗りつぶし（前景色／背景色／透明）
fill_rectangle	矩形領域を塗りつぶし
fill_ellipse	楕円領域を塗りつぶし
draw_line	線を描画（鉛筆またはブラシ）
draw_rectangle	矩形の輪郭を描画
draw_ellipse	楕円の輪郭を描画
gradient_fill	線形または放射状のグラデーションを適用
set_colors	前景色／背景色を設定

🔤 テキスト

ツール	説明
add_text	テキストレイヤーを追加
edit_text	既存のテキストレイヤーを編集
list_fonts	使用可能なフォントを一覧表示

✨ フィルターと効果

ツール	説明
apply_gaussian_blur	ガウスぼかしフィルター
apply_pixelate	ピクセル化／モザイク効果
apply_emboss	エンボス効果
apply_vignette	ビネットによる暗化
apply_noise	ノイズ／粒状感を追加
apply_drop_shadow	ドロップシャドウ効果

📁 ファイル操作

ツール	説明
open_image	画像ファイルを開く
export_image	PNG、JPEG、BMP、TIFF 形式でエクスポート
new_canvas	空のキャンバスを作成
close_image	画像を閉じる
list_images	開いている画像を一覧表示

🔍 情報とコンテキスト

ツール	説明
get_image_metadata	画像サイズ、モード、レイヤー、ファイル名
get_gimp_info	GIMP のバージョン、プラットフォーム、機能
get_context_state	現在の色、ブラシ、不透明度、モード
get_pixel_color	指定したピクセルの色の値
get_histogram	チャンネルのヒストグラムデータ
get_selection_bounds	現在の選択範囲の境界

---

AI エージェントのフィードバックループ

get_state_snapshot ツールを使うと、目標が視覚的に確認できるまで AI が繰り返し処理するパターンを実現できます。

┌─────────────┐
│  Apply edit │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ get_state_      │  ← AI sees live PNG, no disk save needed
│ snapshot()      │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐     ┌──────────────────┐
│ Goal achieved?  │─ No─▶ Adjust & retry   │
└──────┬──────────┘     └──────────────────┘
       │ Yes
       ▼
┌─────────────┐
│   Export    │
└─────────────┘

例：背景の反復削除

完全な例については、bg_remove_iterative.py を参照してください。AI は次の処理を行います。

1. エッジをシードにした隣接領域選択を使用して背景を削除します
2. スナップショットを撮って結果を確認します
3. 背景色が残っているピクセルをスキャンします
4. グリッドを徐々に細かくしながら（25px → 1px）、対象を絞った削除処理を実行します
5. 孤立したピクセルを対象に、最後の点描除去処理を実行します
6. 背景ピクセルがなくなるまで繰り返します

---

スクリプトの例

スクリプト	説明
run_tests.py	56 件のテストスイート — 使用している GIMP に対して実行し、すべてのツールが動作することを確認します
bg_remove_iterative.py	スナップショットによるチェックポイントを使った、背景の反復削除
bg_remove.py	1 回の処理で背景を削除するシンプルなスクリプト
agent_edit_demo.py	完全なパイプライン：開く → 背景を削除 → 表情を編集 → エクスポート

テストスイートを実行して、セットアップを確認してください。

python run_tests.py
# Expected: 56/56 PASSED

---

技術アーキテクチャ

プラグインとサーバー間の通信

AI Client (Claude, etc.)
      │  MCP (stdio)
      ▼
gimp_mcp_server.py          ← MCP tool definitions
      │  TCP JSON  :9877
      ▼
gimp-mcp-plugin.py          ← Runs inside GIMP process
      │  PyGObject
      ▼
GIMP 3.2 (gi.repository.Gimp)

• MCP サーバーはツール呼び出しを JSON コマンドに変換し、TCP 経由でプラグインに送信します
• プラグインは PyGObject 経由で GIMP プロセス内から直接処理を実行します
• メッセージ形式は 2 種類あります。名前付きツールには {"type": "...", "params": {...}} を、任意の exec には {"cmds": ["python..."]} を使用します

GIMP 3.2 との互換性に関する注意

GIMP 3.x では、GIMP 2.x から互換性を損なう API の変更が導入されました。このリリースには、主に次の修正が含まれています。

問題	修正
layer.copy(False) → エラー	GIMP 3.2 の layer.copy() は引数を取りません
Gimp.text_fontname() が削除	PDB の gimp-text-fontname を使用します
gimp-blend が削除	GEGL の gegl:linear-gradient / gegl:radial-gradient を使用します
曲線で GimpDoubleArray の TypeError が発生	drawable.curves_spline() を直接使用します
Gimp.fonts_get_list() が Font オブジェクトを返す	JSON にシリアライズする前に .get_name() で変換します
image.select_none() が削除	PDB の gimp-selection-none を使用します
layer.get_pixel() が Gegl.Color を返す	.get_rgba() で浮動小数点の各成分を取り出します

---

トラブルシューティング

「GIMP に接続できません」

• GIMP が起動しており、画像が開かれている必要があります
• MCP サーバーを起動します：ツール > MCP サーバーを起動
• ポート 9877 がファイアウォールでブロックされていないことを確認します

プラグインが GIMP に表示されない

• ツール > MCP を確認します（プラグインはトップレベルの「ツール」項目ではなく、MCP サブメニューを追加します）
• プラグインファイルが正しいディレクトリにあることを確認します（上記のインストール手順を参照）
• 最近 GIMP をアップグレードしましたか？ マイナーアップグレード（例：3.0 → 3.2）によってユーザーごとの設定フォルダーが新しいバージョン用のディレクトリに移動するため、新しいバージョンの plug-ins フォルダーにプラグインを再インストールしてください。編集 > 設定 > フォルダー > プラグイン で有効なパスを確認できます。
• Linux/macOS の場合：ファイルに実行権限があることを確認します（chmod +x）
• インストール後に GIMP を再起動します
• エラーメッセージがないか、フィルター > Script-Fu > コンソール を確認します

テストが失敗する

テストスイートを実行し、失敗の一覧を確認します。

python run_tests.py

各失敗にはツール名とエラーが含まれています。GIMP 3.2 で発生する問題のほとんどは、上記の修正で解決できます。

デバッグモード

GIMP_MCP_DEBUG=1 uv run --directory /path/to/gimp-mcp gimp_mcp_server.py

---

出力例

「顔と羊を描いて」— GIMP MCP を介して、自然言語だけで生成

---

今後の機能強化

• 📚 レシピ集：再利用可能なワークフローテンプレート（ポートレートの補正、商品写真など）
• ↩️ 元に戻す機能：MCP 経由での履歴管理とロールバック
• 🚀 動的な検出：GIMP の PDB プロシージャデータベース全体から MCP ツールを自動生成
• 🔒 セキュリティ：信頼できないコマンド入力をサンドボックスで実行
• ⚡ パフォーマンス：大きな画像のビットマップ転送を最適化
• 🌐 リモートアクセス：ネットワーク経由でアクセス可能な GIMP インスタンス

---

貢献

バグ修正、新しいツール、ドキュメント、サンプルスクリプトなどの貢献を歓迎します。GitHub で PR または issue を作成してください。

開発環境のセットアップ

開発用の依存関係をインストールし、pre-commit フックを有効にすると、コミットのたびに ruff が実行されます。

uv sync
uv run pre-commit install

これにより、各 git commit でステージング済みファイルが ruff によってチェックされます（--fix は自動的に適用されます）。同じチェックは CI でも実行されるため、このフックはローカルで素早く確認するための安全策です。

後で固定されたフックのバージョンを更新するには：

uv run pre-commit autoupdate