Image Gen

image-gen-mcp

お使いの API キーを使って、コーディングエージェントから画像を生成・編集できます。ブログのカバー画像やロゴの調整、仮のイラストを依頼すると、ファイルはエージェントが読み込んで修正できるよう、プロジェクト内に直接保存されます。

Google Gemini の画像モデル（Nano Banana ファミリー）と OpenAI GPT の画像モデルを、単一のインターフェースから利用できます。いずれか一方、または両方のプロバイダーを設定してください。

_{このバナーとリポジトリのソーシャルプレビューカードは、どちらもこのサーバーで gemini-3.1-flash-image を使い、16:9 2K で生成されました。プロンプトは assets/README.md にあります。}

インストール

claude mcp add image-gen --scope user \
  --env GEMINI_API_KEY=your-gemini-key \
  --env OPENAI_API_KEY=your-openai-key \
  -- npx -y @nuver-labs/image-gen-mcp

新しい Claude Code セッションを開始して設定を反映し、claude mcp list を確認してください。

つまずきやすい点は3つあります。

• 最後の --env とサーバー名の間には、少なくとも1つのオプションが必要です。 上の例では、--scope がその役割を果たします。--env のキーと値のペアの直後に名前を置くと、CLI はそれを別の KEY=value として読み取ります。
• コマンドの前に -- を付ける必要があります。 付けないと、サーバー独自の引数が Claude Code の引数として解析されます。
• 使用しないプロバイダーの --env 行は削除してください。少なくとも1つは必要です。

キーは Google AI Studio と OpenAI platform から取得できます。

その他のクライアント

どの環境でも同じパッケージを使用します。.mcp.json（プロジェクトスコープ。コミットしてください）と Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）の場合：

{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "@nuver-labs/image-gen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Claude Code ではサーバーごとに "timeout": 600000 も設定できますが、Claude Desktop では設定できません。Cursor では .cursor/mcp.json で同じ形式を使います。Windows では、GUI ホストが npx を見つけられないことがあるため、"command": "cmd" と "args": ["/c", "npx", "-y", "@nuver-labs/image-gen-mcp"] を使用してください。

使い方

自然な言葉で依頼するだけです。

• 「夕暮れ時の灯台を描いた16:9のヒーロー画像を生成して、assets/hero.png に保存して」
• 「public/logo.png の背景を透明にして」
• 「シンプルな紙飛行機アイコンを正方形で3パターン作って、design/drafts/ に保存して」

エージェントは generate_image または edit_image を、プロジェクト内の絶対パスである output_path とともに呼び出します。ファイルはディスクに保存され、エージェントは保存先のパスを読み込んで結果を確認し、調整できます。呼び出しに失敗した場合は、list_capabilities を実行して、実際に設定されている内容を確認するよう依頼してください。

ツール

ツール	機能
generate_image	テキストプロンプトから1つ以上の画像ファイルを生成します。保存先の絶対パスを返します。
edit_image	テキストの指示に従って、既存の画像を編集または合成します。元の画像が上書きされることはありません。
list_capabilities	設定されているプロバイダー、デフォルトのモデル、出力ディレクトリのルールを確認できます。

generate_image

引数	型	備考
prompt	string、必須	被写体、スタイル、構図、色、描画するテキスト
output_path	string	絶対ファイルパス（.png/.jpg/.webp）またはディレクトリです。ディレクトリを指定すると、ファイル名はプロンプトからスラッグ化されます
provider	gemini | openai	デフォルトのプロバイダーを上書きします
model	string	Gemini：gemini-3.1-flash-image（デフォルト）、gemini-3.1-flash-lite-image、gemini-3-pro-image、gemini-2.5-flash-image。OpenAI：gpt-image-2（デフォルト）、gpt-image-1.5、gpt-image-1、gpt-image-1-mini
aspect_ratio	1:1 2:3 3:2 3:4 4:3 9:16 16:9 21:9	Gemini と gpt-image-2 では正確に指定できます。旧バージョンの OpenAI モデルでは概算となり、横長は 1536x1024、縦長は 1024x1536 になります
n	1-4	Gemini は順番に生成するため、n>1 の場合は時間がかかります
quality	low medium high auto	OpenAI のみ。安価な下書きには low を指定します
background	transparent opaque auto	OpenAI のみ。ロゴやアイコンに最適です。gpt-image-1.5 以前が必要なため、gpt-image-2 で transparent を指定すると gpt-image-1.5 に自動で切り替わり、結果にもその旨が表示されます
image_size	1K 2K 4K	Gemini 3.x のみ
return_image	boolean	最初の画像もインラインで返し、読み込みなしでモデルが確認できるようにします。コンテキストトークンを消費します

edit_image

上記のすべてに加えて、次の引数があります。

引数	型	備考
source_paths	string[]、必須	絶対パス（.png/.jpg/.jpeg/.webp）を1～16件指定します。最初のパスが編集対象で、残りは参照画像です。Gemini では1～3件が最適です
input_fidelity	low | high	OpenAI のみ。high は顔、ロゴ、細部を保持します。常に高忠実度の gpt-image-2 では無視されます

output_path を省略すると、結果は最初のソース画像と同じディレクトリに保存されます。

list_capabilities

引数はありません。設定済みのプロバイダーを真偽値（キーの値は含みません）で報告し、デフォルトのプロバイダーとモデル、既知のモデルオプション、出力ディレクトリのフォールバック順、および適用中のディレクトリ制限を表示します。

設定

変数	デフォルト	用途
GEMINI_API_KEY	（未設定）	Gemini プロバイダーを有効にします
OPENAI_API_KEY	（未設定）	OpenAI プロバイダーを有効にします
IMAGE_GEN_MCP_DEFAULT_PROVIDER	キーに基づく	gemini または openai。未設定の場合、Gemini のキーが設定されていれば gemini、そうでなければ openai になります
IMAGE_GEN_MCP_GEMINI_MODEL	gemini-3.1-flash-image	デフォルトの Gemini モデル
IMAGE_GEN_MCP_OPENAI_MODEL	gpt-image-2	デフォルトの OpenAI モデル
IMAGE_GEN_MCP_OUTPUT_DIR	（未設定）	呼び出し時に output_path が渡されなかった場合のフォールバック出力ディレクトリ
IMAGE_GEN_MCP_ALLOWED_DIRS	（未設定）	読み書きの対象をこのカンマ区切りのディレクトリ内に制限します。セキュリティを参照してください
IMAGE_GEN_MCP_TIMEOUT_MS	180000	プロバイダー API へのリクエストごとのタイムアウト
IMAGE_GEN_MCP_LOG_FILE	~/.image-gen-mcp/images.jsonl	JSONL 台帳のパスです。別の場所に移動するには絶対パスを指定し、ファイルへの記録を無効にするには none を指定します

output_path を指定しない場合、ファイルは次のうち最初に利用可能な場所に保存されます：IMAGE_GEN_MCP_OUTPUT_DIR、 CLAUDE_PROJECT_DIR（Claude Code によって設定され、現在のプロジェクトを指します）、サーバーの作業ディレクトリ。

セキュリティ

このサーバーは、ユーザーの完全な権限でローカルに実行され、MCP クライアントによるサンドボックス化はされません。すべてのツールの使用を承認する前に、この点を理解しておくことをおすすめします。

できること。 画像ファイルをディスクに書き込みます。edit_image に指定した画像ファイルを読み込みます。プロンプトと、edit_image のソース画像を選択したプロバイダーに送信します。料金が発生する API 呼び出しを行います。機能はこれだけです。ツールは 3 つで、シェルの実行、任意の URL の取得、テレメトリーはありません。

ファイルアクセス。 output_path と source_paths はモデルが選択し、デフォルトでは制限されません。これにより、エージェントが作業中の任意のプロジェクトに保存でき、ツールが役立つものになります。Claude Code の作業ディレクトリの境界は MCP サーバーには適用されず、Anthropic はサードパーティ製 MCP サーバーのセキュリティ監査を行っていません。

明確な境界を設けるには、IMAGE_GEN_MCP_ALLOWED_DIRS を設定します。

IMAGE_GEN_MCP_ALLOWED_DIRS=/Users/you/projects,/Users/you/Desktop

以降、すべての出力パスと edit_image のソースは、いずれかのルート内に解決される必要があります。パスは realpath で解決した後に比較されるため、ルート外を指すシンボリックリンクは拒否されます。また、包含関係の判定には文字列のプレフィックスではなくパスのセグメントを使うため、/Users/you/projects-private のような隣接ディレクトリがすり抜けることはありません。設定した項目がどれも存在しない場合、サーバーは制限なしで実行するのではなく、すべてのファイルアクセスを拒否します。

API キー。 キーは環境変数からのみ読み込まれ、プロバイダー SDK のコンストラクターに渡され、それ以外の用途には使われません。ログに記録されることも、台帳に書き込まれることもなく、ブール値を返す list_capabilities から返されることもありません。

リスクは、このサーバーがキーをどう扱うかではなく、キーをどこに置くかにあります。~/.claude.json や claude_desktop_config.json に直接記述したキーはプレーンテキストで保存され、あなたとして実行中のあらゆるプロセスから読み取れます。また、自身の設定を読むよう求められたエージェントが、キーを会話記録に出力する可能性もあります。シェルプロファイルまたはシークレットマネージャーから環境変数として設定し、設定ファイルに chmod 600 を実行したうえで、共有の本番キーではなく、使用額の上限を設定した専用キーを使うことをおすすめします。

利用料金。 組み込みのレート制限や上限はありません。再試行ループに入ったエージェントは、短時間に大量の画像を生成する可能性があります。OpenAI のハード利用上限を設定し、Google Cloud の予算アラートも設定してください。

ローカルログ。 ~/.image-gen-mcp/images.jsonl にある台帳には、各プロンプトの一部がプレーンテキストで保存され、無制限に増加します。IMAGE_GEN_MCP_LOG_FILE=none で無効にし、コミットしないでください。

プロンプトインジェクション。 ツールの結果はモデルのコンテキストに戻されます。このサーバーを常に許可するのではなく、呼び出しごとに承認することをおすすめします。承認時には、出力パスと edit_image のソースパスも確認してください。アップグレードの前に、バージョンを固定し、差分を確認してください。

脆弱性を発見しましたか？SECURITY.mdを参照してください。公開のイシューは作成しないでください。

ロギング

呼び出しが正常に完了するたびに、構造化 JSON エントリーが 2 つの方法で記録されます。

• stderr：常に記録されます。[image-gen-mcp] image {...} という 1 行が /mcp の出力と Claude Code のログに表示されます。
• JSONL 台帳：デフォルトで有効です。同じ JSON が ~/.image-gen-mcp/images.jsonl に追記され、呼び出しごとに 1 行記録されます。台帳への書き込みに失敗しても生成は中断されず、stderr に警告が 1 回表示されます。

各エントリーには、プロバイダー、モデル、要求されたサイズ、経過秒数、文字数とともに一部を省略したプロンプト、プロバイダーから報告された場合のトークン使用量、画像ごとの詳細（保存先のパス、バイトサイズ、人が読みやすい形式のサイズ、MIME タイプ、実際のピクセル寸法）が記録されます。

tail -n 20 ~/.image-gen-mcp/images.jsonl
jq 'select(.usage) | .usage.totalTokens' ~/.image-gen-mcp/images.jsonl

コスト

呼び出しごとに有料 API を利用し、通常は画像 1 枚あたり数セントかかります。費用はプロバイダー、モデル、品質、サイズによって異なります。下書きには、低コストのオプションとして OpenAI の quality: low（gpt-image-2 で 1024x1024 の低品質画像を生成する場合、約 $0.006）、または gpt-image-1-mini、Gemini の gemini-3.1-flash-lite-image があります。Gemini の gemini-2.5-flash-image は、請求設定のないキーで無料枠が利用できる場合があるため、IMAGE_GEN_MCP_GEMINI_MODEL=gemini-2.5-flash-image を設定するとデフォルトになります。

タイムアウト

生成には、モデルとサイズに応じておよそ 10〜120 秒かかります。Claude Code のデフォルト設定には十分な余裕があり、このサーバーは長時間の呼び出し中に進行状況の通知を送信するため、通常は調整する必要はありません。グローバルな MCP_TOOL_TIMEOUT を短く設定している場合は、.mcp.json にサーバーごとの "timeout": 600000 を追加してください。

トラブルシューティング

• サーバーのログは、[image-gen-mcp] というプレフィックス付きで stderr に出力されます。Claude Code では、/mcp の出力とログに表示されます。
• 登録済みなのにツールがない場合：新しいセッションを開始し、claude mcp list と claude mcp get image-gen を確認してください。
• Provider 'x' is not configured：そのキーが MCP サーバーの環境に設定されていません。--env フラグを指定して再登録するか、設定を編集してください。
• 出力先が許可されたディレクトリの範囲外の場合：IMAGE_GEN_MCP_ALLOWED_DIRS が設定されています。list_capabilities を実行してルートを確認してください。
• レスポンスが大きすぎる場合：return_image は画像全体をインラインで含めるため、MCP の出力トークン上限（MAX_MCP_OUTPUT_TOKENS、デフォルトは 25k）を超えることがあります。これをオフにして、エージェントが保存済みファイルを読み込めるようにしてください。
• Gemini が拒否する場合：エラーには終了理由とプロバイダーからのテキストが含まれます。プロンプトを言い換えてください。

ソースからビルドする

Node 22 以降と pnpm が必要です。

git clone https://github.com/nuver-labs/image-gen-mcp.git
cd image-gen-mcp
pnpm install
pnpm build

クライアントの接続先を npx -y @nuver-labs/image-gen-mcp ではなく、node /abs/path/to/image-gen-mcp/dist/index.js に設定してください。

pnpm test      # unit tests, no API keys needed
pnpm inspect   # list the tools over real MCP stdio

# Live tests. These cost real API credits.
GEMINI_API_KEY=... node dist/smoke.js --provider gemini
OPENAI_API_KEY=... node dist/smoke.js --provider openai
node dist/smoke.js --provider gemini --edit ./smoke-output/smoke-gen-gemini.png

コントリビューション

バグ報告、プロバイダー固有の問題の修正、ドキュメントの改善を歓迎します。CONTRIBUTING.md をご覧ください。大規模な変更を行う場合は、まず issue を作成してください。

予定：OpenAI のマスク処理とインペインティングへの対応、従来の Gemini generateContent 画像生成パスから Interactions API への移行、その他のプロバイダーへの対応。

ライセンス

MIT

---

Nuver Labs が開発しました。