gpt-image-mcp

Claude Code に画像生成のスーパーパワーを。 「絵を描いて」と言うと、 Claude Code は、OpenAI gpt-image-2 を使って会話の中で即座に画像を生成します — アプリを切り替えたりプロンプトをコピーする必要はありません。

🎯 これは何？

Claude Code ユーザー向け: このプロジェクトは、gpt-image-2 の画像生成を Claude Code に MCP サーバーとして直接組み込みます。一度インストールして一度登録すれば、Claude Code はネイティブの generate_image 機能を獲得します — 画像を平易な言葉（どの言語でも）で説明すると、Claude Code がプロンプトを作成し、gpt-image-2 を呼び出し、ローカル PNG を渡します。もしこれまで Claude に説明ではなく「そのまま描いて」ほしかったなら、これこそが欠けていたピースです。

スタンドアロン CLI や他の MCP ホストでも動作します — 同じコアがどこでも機能します。

ChatGPT Plus のサブスクリプションは不要 — gpt-image-2 に対応した API キーだけで十分です。

Workflow:

You: "A cyberpunk orange tabby cat in a spacesuit, starfield, cinematic lighting"
  ↓  Claude Code optimizes your prompt into professional English (automatic)
  ↓  gpt-image-mcp calls OpenAI gpt-image-2
  ↓  PNG saved locally → absolute path returned
You: got your image ✓

Related MCP server: gpt-image-mcp

✨ 特徴

• ネイティブ Claude Code 統合。 一度登録すれば、Claude Code は実際の generate_image ツールを獲得します — 任意のシーンを平易な言葉で説明すると、チャット内でローカル PNG を受け取れます。

• 2つのエントリポイント、1つのコア。 同じ生成ロジックが MCP サーバーとプレーン CLI の両方を支えます。

  • gpt-image-mcp --mcp → generate_image / list_images ツールを備えた stdio MCP サーバー

  • gpt-image-mcp "a cat in a spacesuit" → ワンショット CLI 生成

• あらゆる OpenAI 互換バックエンド。 OPENAI_BASE_URL を好きな場所（リセラー、プロキシ、セルフホストゲートウェイ）に指定できます。

• 品質ティア は gpt-image-2 独自の low / medium / high ノブに対応しています。追加モデルも、予想外のコストもありません。

• コードにキーを記載しない。 すべて環境変数で駆動 — シークレットはリポジトリの外に保持されます。

• 非同期セーフ。 画像は base64 デコードされた PNG としてローカルのディスクにストリーミングされます。API があなたのディスクに書き込むことはありません。

🧰 要件

• Python 3.10+

• gpt-image-2（または GPT_IMAGE_MODEL で設定した互換モデル）を提供する OpenAI API キー、または OpenAI 互換エンドポイント（リセラー / ゲートウェイ / セルフホスト）

• pip または uv でインストール可能な Python

📦 インストール

PyPI から

pip install gpt-image-mcp           # pip
# or
uv tool install gpt-image-mcp       # uv

ソースから

git clone https://github.com/Garfield-Wuu/gpt-image-mcp
cd gpt-image-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .

⚙️ 設定

すべての設定は環境変数を介して行います:

ヒント: デフォルトのベース URL は公式 OpenAI エンドポイントです。リセラーやプロキシを使うには、OPENAI_BASE_URL をその /v1 ルートに設定するだけです — 他に変更はありません。

🚀 使い方

MCP サーバーとして（Claude Code）

サーバーを登録します（~/.venv は実際の環境パスに置き換えてください）:

claude mcp add gpt-image -s user \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  --env GPT_IMAGE_OUT="$PWD/out" \
  -- gpt-image-mcp --mcp

Claude Code を再起動すると、2つのツールが利用可能になります:

• generate_image — 画像を生成してローカルに保存します。

  ┌─────────────────────────────────────────────────────────────┐
  │ "A cyberpunk orange tabby cat in a spacesuit …"             │
  │    → gpt-image-mcp → local PNG → absolute path returned    │
  └─────────────────────────────────────────────────────────────┘

  パラメータ: prompt（必須）、size、quality、out_name。

• list_images — 以前に生成した PNG を一覧表示します（新しい順）。

Claude Code での話しかけ方:

「宇宙服を着たサイバーパンクなオレンジのトラ猫、星空、映画的、高品質。」 → generate_image を起動

「雨の中のサイバーパンクシティ、ネオンの反射、1536x1024 の横長ヒーローショットを 生成して。」 → size と quality を設定

「これまでに生成した画像はどれ？」 → list_images を起動

特別な構文は不要です — 画像を自分の言葉で、どの言語でも説明するだけです。 Claude Code が残りを処理します。

CLI として

export OPENAI_API_KEY="sk-..."
gpt-image-mcp "a cyberpunk orange tabby cat, neon rain, cinematic" \
  --size 1536x1024 --quality high --out ./out/hero.png

--no-interactive を付けない場合、CLI は TTY が存在するときに サイズ/品質を対話的に選択できます。

🖼️ パラメータ

size — キャンバスの向き:

quality — gpt-image-2 独自の品質ノブ（単一モデル。速度/コストと詳細のトレードオフ）:

🛠️ 開発

pip install -e ".[dev]"
ruff check .            # lint
pytest                  # run tests
python -m build         # build sdist + wheel

レイアウト:

src/gpt_image_mcp/
├── img_core.py    # shared generation logic (no MCP dependency)
├── mcp_server.py  # FastMCP server: generate_image / list_images
└── __main__.py    # CLI + MCP entrypoints

🔐 セキュリティ

• API キーがこのパッケージに埋め込まれることはありません。 呼び出し時に OPENAI_API_KEY から読み取られます。

• 単一の画像生成リクエスト以外に、ログに記録されたり送信されたりするものはありません。

• .env と out/ ディレクトリはデフォルトで git 無視されます。

📝 注記と注意点

• 各リクエストは通常、エンドポイントと品質ティアに応じて約 10〜60 秒かかります。

• このプロジェクトは OpenAI とは提携していません。独立した MCP ラッパーです。

• gpt-image-2 はデフォルトで画像を base64 で返しますが、このツールはそれをデコードしてローカルのディスクに書き込みます。url フォールバックも処理されます。

📄 ライセンス

MIT © Garfield-Wuu.

⭐ サポート

これで面倒な調査から救われたなら、スターをいただけると嬉しいです。Issue と PR も歓迎します。

🌐 他の言語 / 其他语言

• 中文版 README (README.zh-CN.md) — 简体中文