GIMP Studio MCP

GIMP Studio MCP

TwelveTake Studios のプロジェクトです。

MCP Registry には mcp-name: com.twelvetake/gimp-studio-mcp として登録されています。

GIMP Studio MCP は、AI アシスタントが GIMP 3 で画像を編集できるようにする Model Context Protocol サーバーです。すべてのツールはエラーを記録した構造化された結果を返し、チェックポイントを使えば要求に応じて画像を以前の状態に復元できます。印刷および DTF（ダイレクト・トゥ・フィルム）転写の制作向けツールも含まれています。

13 グループにわたる 119 個のツールを搭載し、すべて実際の GIMP インスタンスでテスト済みです。

ステータス： ベータ版。GIMP 3.2.4 で、ヘッドレス環境と通常環境の両方でテスト済みです。0.3.3 までのリリースも GIMP 3.0.4 でテストされています。

このサーバーを選ぶ理由

印刷および DTF 制作を中心に設計されています。印刷解像度での実寸、ガーメントカラーのノックアウト、フィルム出力にそのまま使える透明 PNG に対応しています。すべてのツールが構造化された結果を返すため、通常の編集でアシスタントが GIMP Python を記述する必要はありません。

設計ルール（すべてのツールに適用）

1. 構造化された戻り値： { ok, result, stdout, warnings, error }。エラー時でも出力が失われません。
2. 生の exec を維持： 万能なエスケープハッチ（gimp_exec）を、適切なキャプチャ機能とともに残しています。（GIMP_MCP_NO_EXEC=1 で無効化できます。セキュリティモデルを参照してください。）
3. 互換性／癖への対応レイヤー： 1 つのモジュールで GIMP 3 の相違点と既知の問題に対応します。
4. モードに依存しないツール： GIMP が通常モード（キャンバスが表示された状態）でもヘッドレスでも、同じように動作します。
5. ビジョンファースト： get_bitmap はエージェントが実際に確認できる表示用画像を返します（領域／スケール／バイト数の上限を指定可能）。これにより自己検証ができます。
6. デフォルトで安全： 破壊的な操作の前後に checkpoint／restore を使用します。
7. すべての箇所でパラメーターを検証します。
8. 印刷を全体で考慮： DPI／インチを基本機能として扱い、DTF 出力を主要機能としています。

アーキテクチャ（初日からハイブリッド）

通常モードとヘッドレスモードの違いは誰が GIMP を起動するかだけであり、通信方法は同じです。そのためブリッジは 1 つです。

• 通常モード： 永続的な GIMP 拡張機能（gimp-mcp install-plugin でインストール）が起動時に開始し、ループバックエンドポイントを公開します。MCP サーバーは実行中の GIMP に自動接続し、キャンバスを表示します。
• ヘッドレス： 実行中の GIMP が見つからない場合、サーバーは長時間稼働する gimp -i を起動し、同じブリッジを読み込みます。

どちらも、ループバック TCP、長さプレフィックス付き JSON、トークン認証を使う同一のプロトコルで通信します。ピクセルのエクスポートはどちらでも動作します。

機能分野（119 個のツール）

グループ	ツール	対応内容
セッション	5	ヘルス／ステータス、開いている画像の一覧、アクティブ画像の切り替え、未加工の gimp_exec、名前空間のリセット
ドキュメント	4	画像の新規作成／開く、メタデータ、アルファを保持したエクスポート（透明度を保持）
レイヤー	18	作成／複製／削除／並べ替え／移動、不透明度、ブレンドモード、グループ、統合、コンテンツのオフセット＋継ぎ目チェック（タイル可能なテクスチャ）
マスクとアルファ	9	マスクの追加／適用／削除、アルファの追加／ロック、アルファ↔選択範囲、輝度→アルファ、色→アルファ（ソフト）＋cutout_color（輪郭のくっきりしたハードなノックアウト）
選択範囲	15	矩形／楕円／色による選択／ファジー選択／パスから／アルファから、拡大／縮小／ぼかし／境界線、反転、チャンネル化、foreground_select（エッジを考慮した被写体の切り抜き／マッティング）
ペイント	10	鉛筆／ペイントブラシ、塗りつぶし、グラデーション、ストローク、描画色／背景色＋ブラシ＋不透明度のコンテキスト
テキスト	5	テキストレイヤーの作成／編集、プロパティ、アウトライン、フォントの確認／置換
色と階調	10	明るさ／コントラスト、レベル、カーブ、色相／彩度、カラーバランス、彩度を下げる、ポスタリゼーション、反転、しきい値、自動正規化（コントラストを自動ストレッチ）
フィルターと効果	4	ガウスぼかし、アンシャープマスク、ドロップシャドウ、汎用 GEGL の apply_filter
印刷／DTF	13	ホワイトアンダーベース、エッジのチョーク／スプレッド、コンテンツに合わせてトリミング、knockout_background（衣類を考慮）、DTF 用クリーニング、ハーフトーン分版、ギャングシート（22″@300）、DTF PNG エクスポート、ジオメトリ／ブリード
カラーマネジメント	7	ICC プロファイルの割り当て／変換、グレースケール／RGB 変換、プロファイルの検査
分析	12	get_bitmap（表示可能なプレビュー）、ヒストグラム（知覚ベース、levels と一致）、色の取得、領域の読み取り、メタデータ、オペレーションの説明、GEGL／プロシージャの一覧
安全性	7	チェックポイント／復元（スクリプト可能なロールバック）、アンドゥグループ、チェックポイントの一覧

ツールは MCP クライアントを通じて自己記述されます。describe_op および list_* ツールで、実行時にオペレーションとリソースを列挙できます。

要件

• GIMP 3.x（3.2.4 でテスト済み）
• Python 3.10+（MCP サーバー用）
• MCP 対応の AI アシスタント（例：Claude Code／Claude Desktop）

インストール

1. サーバーをインストールする

PyPI から：

pipx install twelvetake-gimp-studio-mcp

または、クローンから：

git clone https://github.com/TwelveTake-Studios/gimp-studio-mcp
cd gimp-studio-mcp
pip install -e .

2. GIMP 側のブリッジをインストールする

gimp-mcp install-plugin     # copies the bridge into GIMP's plug-ins dir
gimp-mcp doctor             # verify install + GIMP exe + bridge reachability

GIMP を再起動してください（次回起動時に読み込まれます）。ブリッジは永続的な拡張機能として自動起動します。

3. MCP クライアントに登録する

クライアントの MCP 設定（例：.mcp.json）に追加します。

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

利用可能な場合、サーバーは起動中の GIMP に接続し、そうでない場合はヘッドレス GIMP を自動的に起動します。常にヘッドレスで実行するには、GIMP_MCP_HEADLESS=1 を設定します。

クイックスタート

一般的な編集

"Open logo.png and tell me its size and layers"
"Add a 12px white outline to the text layer"
"Auto-crop the image to its content, then export a transparent PNG"
"Show me the current canvas"          → get_bitmap returns a viewable preview

DTF（ダイレクト・トゥ・フィルム）— 主なワークフロー

"Knock out the black shirt color behind this artwork"     → knockout_background, garment-aware
"Add a white underbase choked 2px so it doesn't peek"      → white_underbase + edge_choke
"Clean this up for DTF and export a 300-DPI transparent PNG"
"Gang up 12 copies of this design onto a 22-inch sheet at 300 DPI"

knockout_background は衣類を考慮します。shirt= プリセット（black、navy、heather_gray、red など）を渡すと、適切な除去方法を選択します（黒い衣類で黒がシャツの透けた部分に見える場合は色からアルファへ変換し、明るい色や彩度の高い衣類では選択範囲を作成してハードクリアします）。list_shirt_presets でカタログを確認できます。

セキュリティモデル

このサーバーは、ローカルユーザーと同じ信頼境界で実行されます。インストールすると、接続された AI エージェントがこのマシン上の GIMP を操作できるようになり、さらに gimp_exec を通じて GIMP のプロセス内で任意の Python を実行できるようになります。これはシングルユーザーのワークステーションを想定したものであり、サンドボックスではありません。

• ループバックのみ＋トークン。 ブリッジはエフェメラルポートとセッションごとのトークンを使用して 127.0.0.1 で待ち受けます。ネットワークには公開されません。
• gimp_exec は設計上、ホスト上の任意コードを実行できます。 悪意のある指示やプロンプトインジェクションされた指示（たとえば、エージェントに開かせる画像に隠されているもの）が gimp_exec に到達する可能性があります。信頼できるエージェントとコンテンツのみを接続してください。
• 無効化スイッチ。 GIMP_MCP_NO_EXEC=1 を設定すると、gimp_exec の登録を完全にスキップできます。他の 118 個の構造化ツールは引き続き動作します。

詳しい脅威モデルと報告手順については、SECURITY.md を参照してください。

環境変数

変数	効果
GIMP_MCP_HEADLESS	実行中の GIMP に接続する代わりに、常にヘッドレスの GIMP（gimp -i を起動）を実行します（1／true／yes／on）。
GIMP_MCP_NO_EXEC	生の gimp_exec ホストコード実行ツールの登録をスキップします（1／true／yes／on）。
GIMP_MCP_DISABLED	GIMP 内のブリッジは応答しますが、サービスを提供しません。
GIMP_MCP_ENDPOINT_FILE	エンドポイントファイルのパスを明示的に指定します（上級者向け／ヘッドレス）。
GIMP_MCP_PORT	エフェメラルポートの代わりに、ブリッジのポートを固定します。
GIMP_MCP_EXE	サーバーが自動検出できないインストール環境で使用する、GIMP の gimp-console 実行ファイルのパスです。
GIMP3_DIRECTORY	デフォルト以外の GIMP プロファイルフォルダーを指定する、GIMP 独自の変数です。gimp-mcp install-plugin はこのフォルダーにブリッジをインストールし、gimp-mcp doctor はこのフォルダーをチェックします。
GIMP_MCP_OPERATION_TIMEOUT	タイムアウトエラーを返すまでに、個々の GIMP 操作を実行できる秒数です（デフォルトは 120）。
GIMP_MCP_START_TIMEOUT	ヘッドレスの GIMP の起動を待つ秒数です（デフォルトは 60）。
GIMP_MCP_CONNECT_TIMEOUT	GIMP への接続を待つ秒数です（デフォルトは 10）。

トラブルシューティング

まず gimp-mcp doctor を実行してください。インストールを確認し、GIMP の実行ファイルを特定して、ブリッジのラウンドトリップをテストします。ヘッドレスの GIMP も起動して、ラウンドトリップ全体を検証するには、--headless を追加してください。

• GIMP を開いているのに「Bridge not reachable」と表示される場合： gimp-mcp install-plugin を実行し、ブリッジ拡張機能が読み込まれるよう GIMP を再起動したことを確認してください。
• サーバーを編集したのに、ツールに変化が見られない場合： MCP サーバーはホットリロードされません。MCP クライアントのセッションを再起動してください。

ライセンス

MIT — LICENSE を参照してください。

---

TwelveTake Studios LLC ウェブサイト：twelvetake.com お問い合わせ：[email protected]