gpt-image-mcp

OpenAI の画像生成／編集を MCP ツールとして出すサーバ。 同じキャラクターの差分絵（口の形・目の開閉）を作る用途を主目的にしている。

なぜ単なるAPIラッパーではないか

/v1/images/edits は、マスクを渡しても画像全体を再生成する。

実測（2026-08-12・gpt-image-2・1024x1024）:

	マスク内で変化	マスク外で変化	マスク外の最大差分
口を「あ」に編集	7,184px (35.8%)	9,425px (0.92%)	220
口を「い」に編集	1,498px (7.5%)	7,431px (0.72%)	216

最大差分220は「ほぼ別の色」。編集結果をそのまま動画のコマに使うと、口が変わるたびに髪や輪郭も動く—— 30fps で切り替えると顔が揺れる。

このサーバは対処を同梱している。編集結果は「口の形の参考」として扱い、土台は1枚に固定して、 マスク領域だけをローカルで貼り直す（compose_region）。土台はビット単位で保たれる。

	マスク外の最大差分
編集結果をそのまま使う	220
単純にぼかして合成	55（ぼけがマスク外へ滲む）
compose_region（内側だけぼかす）	10（知覚不能）

ツール

ツール	課金	何をするか
list_image_models	なし	このキーで使える画像モデルを列挙。キーが生きているかの確認にも使う
generate_image	あり	プロンプトから生成し、ファイルに保存してパスを返す
edit_image	あり	マスク指定で編集。そのままコマに使わないこと（上記）
compose_region	なし	編集結果のマスク領域だけを土台へ貼る。土台の汚れを自動検証する
make_mask	なし	楕円マスクを作る（比率指定）

画像は base64 で返さずファイルに書いてパスを返す。会話の文脈を食い潰さないため。

APIキーの扱い

このサーバはキーを保持しない。 呼ぶたびに、次の順で解決する。

1. 環境変数 OPENAI_API_KEY
2. macOS Keychain（OPENAI_KEYCHAIN_SERVICE にサービス名を設定した場合）

エラー本文にキーが混ざった場合は [REDACTED] に置換してから返す。

Keychain へ入れる場合（コマンド履歴にキーを残さない形）:

printf 'key: '; stty -echo; read -r K; stty echo; echo
security add-generic-password -a "$USER" -s openai-image -U -w "$K"; unset K

⚠ security の対話入力（-w を引数なしで最後に置く形）は128文字で切り捨てる。 sk-proj- 形式のキーは164文字あるため、上の「値として渡す」形を使うこと。

設定

.mcp.json / Claude Code の MCP 設定に追加する。

{
  "mcpServers": {
    "gpt-image": {
      "command": "node",
      "args": ["/path/to/gpt-image-mcp/src/index.mjs"],
      "env": { "OPENAI_KEYCHAIN_SERVICE": "openai-image" }
    }
  }
}

必要なもの

• Node.js 18+（fetch / FormData を使う）
• Python 3 ＋ Pillow（compose_region / make_mask）。numpy があれば土台の汚れを自動検証する

npm install
pip install Pillow numpy

アバターの作り方（この構成での標準手順）

1. generate_image で土台を1枚作る。背景は単色、影とグラデーションを禁止、正面向き、口は閉じ目は開く
2. make_mask で口の領域（目安 0.40 / 0.455 / 0.60 / 0.575）と目の領域（0.34 / 0.32 / 0.66 / 0.42）のマスクを作る
3. edit_image で口の形（あいうえお）と閉じた目を作る
4. compose_region で全部を土台へ貼り直す ← ここを飛ばすと顔が揺れる
5. 口の形は母音ごとに1枚。日本語の口パクは a i u e o ＋ 閉じ口の6枚で足りる

⚠ 「い」のように変化が小さい口の形は生成が弱い（実測でマスク内の変化が7.5%しか出ず、 マスク外のほうが動いた）。プロンプトを形で具体的に指示するか、その口だけ手で描くほうが早い。

生成物の権利

生成画像を販売物に使う場合、「動画に使ってよい」と「販売する教材に使ってよい」が 別条項のことがある。使う前に、使うキーのアカウントの利用規約を確認すること。 借りたキーで作った素材を自社商品に使わない。

ライセンス

MIT