gemini-image

gemini-image-mcp

Google Gemini のネイティブ画像生成「Nano Banana」モデルに特化した、シンプルな MCP サーバーです。Claude Code、Claude Desktop、または stdio ベースの MCP クライアントから、画像の生成、編集、ローカル処理を行えます。無駄のない 2 つのツールを提供します。

エージェント向けに設計されています。1 回の呼び出しで 保存済みの画像 を返します。また、1 回の呼び出しで背景を削除すれば、そのまま使える透過 PNG を返します。画像データをエージェントのコンテキストにストリーミングする必要はありません。非推奨の Imagen API ではなく、Gemini の generateContent API を使用します。

インストール

npm install -g @jimothy-snicket/gemini-image-mcp

または、npx から直接使用できます。

npx -y @jimothy-snicket/gemini-image-mcp

Claude Code（1 つのコマンドで実行）：

claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp

GEMINI_API_KEY 環境変数が必要です。詳しくはセットアップをご覧ください。

設定ファイルのセットアップ（任意）：

npx @jimothy-snicket/gemini-image-mcp --init

コメント付きのデフォルト設定を含む ~/.gemini-image-mcp.json を作成します。プロジェクト固有の設定で上書きするには、次のようにします。

npx @jimothy-snicket/gemini-image-mcp --init --local

機能

generate_image — AI を活用

• テキストから画像を生成 — 作りたい画像を説明すると、画像が生成されます
• 画像編集 — 参照画像と編集指示を指定します
• 動画から画像を生成 — モデルが動画を 見て 内容を理解し、新しい画像を合成します。YouTube のサムネイル、映像から作るポスター、要約インフォグラフィック、スタイルを変換した静止画などを作成できます。高度な機能をご覧ください
• 思考の深さを制御 — 推論に依存するレンダリング（インフォグラフィック、図、文字量の多い画像）には thinkingLevel: "HIGH" を指定できます。それ以外の場合は、低コストの MINIMAL がデフォルトです
• 1 回の呼び出しで透過素材を生成 — removeBackground は、きれいな透過 PNG を返します。デフォルトではローカルの AI マット処理（あらゆる被写体に対応。オプションのアドオン。詳細は下記）を行い、組み込みのグリーンスクリーンまたは白色しきい値によるキーイングも選択できます。追加の API コストはかかりません
• 複数ターンでの編集 — sessionId を渡すと、以前のターンをコンテキストとして保持しながら、複数回の呼び出しにわたって画像を調整できます
• 複数画像入力 — 編集やキャラクター／スタイルの一貫性維持に参照画像を使用できます（モデルごとに上限があります。上限は API により適用されます）
• コストのレポート — すべての応答にトークン数、推定 USD コスト、セッション合計が含まれます
• レート制限 — リクエスト数とコストに 1 時間あたりの上限を設定し、エージェントの予期しない過剰な実行を防げます
• モデルの自動検出 — 起動時に API キーから利用可能な画像モデルを検出します
• シード値 — 整数シードを使って再現性のある生成を行えます
• 検索グラウンディング — Google 検索の最新結果をレンダリングに反映できます。"web+image" では画像検索結果もムードボードやトレンドの参考資料として取得し、出典を明記できるようソースも返します。高度な機能をご覧ください

process_image — ローカル処理（無料、API 呼び出しなし）

• クロップ — ピクセル単位の正確な指定、アスペクト比に合わせた中央クロップ、または焦点位置の指定（注意度／エントロピー）
• リサイズ — 幅、高さ、またはその両方を指定（アスペクト比を維持）
• 背景の削除 — しきい値ベース（白い背景）またはクロマキー（グリーンスクリーン、任意の単色）
• クロマキー処理パイプライン — HSV キーイング、スムーズステップによる境界のぼかし、色かぶりの抑制、エッジのアンチエイリアス処理
• トリミング — 余白の境界を自動的に削除
• 形式の変換 — PNG、JPEG、WebP。品質を指定できます

両方のツール

• 出力の整理 — 内容に即したファイル名、自動バージョン管理、サブフォルダー
• 生成マニフェスト — generations.jsonl に、すべての生成のプロンプト、パラメーター、コストを記録します
• すべてのアスペクト比に対応 — 1:1、16:9、9:16、3:2、2:3、4:3、3:4、21:9
• 解像度の制御 — 1K、2K、4K

セットアップ

1. Gemini API キーを取得する

Google AI Studio にアクセスして API キーを作成します。

課金が必要です：画像生成には無料枠がありません。無料枠のキーでは、すべての画像モデルで毎回 429 RESOURCE_EXHAUSTED（クォータ上限 0）が返されます。キーの Google Cloud プロジェクトで従量課金を有効にしてください（使用状況と課金）。画像の料金はモデルと解像度に応じて 1 枚あたり約 $0.03～$0.24 です。最も低コストのモデル（デフォルトの gemini-3.1-flash-lite-image）は 1 枚あたり約 $0.034 です。

2. API キーを設定する

サーバーは GEMINI_API_KEY 環境変数からキーを読み取ります。すべてのセッションで使えるように、一度設定してください。

Windows（PowerShell — 管理者として実行）：

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')

その後、ターミナルを再起動してください。

macOS / Linux：

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

（zsh を使っている場合は ~/.zshrc を使用してください。）

設定を確認する：

echo $GEMINI_API_KEY

3. MCP クライアントに接続する

MCP の使用方法に合った方法を選んでください。

Claude Code（ワンライナー）

claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp

Claude Code は環境変数から GEMINI_API_KEY を自動的に取得します。

Claude Code（手動で .mcp.json を設定）

プロジェクトのルートにある .mcp.json に追加するか、グローバルにアクセスできるよう ~/.claude/.mcp.json に追加してください。

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

${GEMINI_API_KEY} の構文はシェル環境から値を読み取ります。実際のキーが設定ファイルに書き込まれることはありません。

Claude Desktop

claude_desktop_config.json を編集してください。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
      }
    }
  }
}

保存後、Claude Desktop を再起動してください。

その他の MCP クライアント

stdio トランスポートをサポートするクライアントであれば、どれでも使用できます。npx -y @jimothy-snicket/gemini-image-mcp を指定し、環境変数として GEMINI_API_KEY を渡してください。

セキュリティに関する注意

• API キーをバージョン管理にコミットしないでください。設定ファイル内の ${GEMINI_API_KEY} 構文は環境変数を参照するため、キー自体はシェルのプロファイルに保持されます。
• .mcp.json がプロジェクトのリポジトリ内にある場合は、.gitignore に追加するか、代わりに ~/.claude/.mcp.json のグローバル設定を使用してください。
• セキュリティをさらに強化するには、OS のキーチェーン（macOS Keychain、Windows Credential Manager）からキーを読み取り、キーを注入してサーバーを起動するラッパースクリプトを使用できます。

設定

すべて任意です。必要な設定は GEMINI_API_KEY だけです（上記を参照）。

変数	デフォルト	説明
OUTPUT_DIR	~/gemini-images	画像の保存先ディレクトリのデフォルト
DEFAULT_MODEL	gemini-3.1-flash-lite-image	デフォルトの Gemini モデル
LOG_LEVEL	info	debug、info、または error
REQUEST_TIMEOUT_MS	60000	API リクエストのタイムアウト（ミリ秒）
MAX_REQUESTS_PER_HOUR	0（無制限）	1 時間の移動期間あたりの画像生成の最大数
MAX_COST_PER_HOUR	0（無制限）	1 時間の移動期間あたりの推定コスト（USD）の上限
SESSION_TIMEOUT_MS	1800000（30min）	複数ターンセッションの有効期限
GEMINI_IMAGE_AUTO_INSTALL	1（オン）	removeBackground: { mode: "auto" } を初めて使用する際に AI マットエンジンを自動インストールします。無効にするには 0 を設定してください（その場合、auto は手順を表示して chroma/threshold にフォールバックします）

GEMINI_API_KEY と同じ方法で設定するか、MCP 設定の env ブロックに指定してください。

エージェントがこのツールを使用できる場合は、レート制限を設定することをおすすめします。ループ中のエージェントは画像をすばやく生成することがあります。妥当なデフォルト値として、MAX_REQUESTS_PER_HOUR=20 と MAX_COST_PER_HOUR=5 を設定してください。

設定ファイル

環境変数の代わりに JSON 設定ファイルを使用できます。次のコマンドで作成してください。

npx @jimothy-snicket/gemini-image-mcp --init

これにより、すべてのデフォルト値とインラインドキュメントを含む ~/.gemini-image-mcp.json が作成されます。ファイルを編集して、好みの設定に変更してください。

優先順位： 環境変数 > ローカル設定（CWD の .gemini-image-mcp.json）> グローバル設定（~/.gemini-image-mcp.json）> デフォルト値。

ツールごとにデフォルト値を設定して、すべてのリクエストに好みの設定を適用することもできます。

{
  "defaultModel": "gemini-3.1-flash-image",
  "defaults": {
    "generate": {
      "aspectRatio": "16:9",
      "resolution": "2K"
    },
    "process": {
      "removeBackground": { "color": "#00FF00" },
      "trim": true
    }
  }
}

リクエストごとのパラメーターは常に設定のデフォルト値より優先されます。

カスタム価格設定。 コストの推定には組み込みのトークン単価テーブルを使用します（最新の価格を取得するための価格 API はありません）。テーブルに未登録のモデルを使う場合、またはこのパッケージが更新される前に Google が単価を変更した場合は、pricingOverrides を追加してください。リリースを待たずに、コストのレポートを正確に保てます。

{
  "pricingOverrides": {
    "some-new-image-model": {
      "inputPerMillion": 0.5,
      "textOutputPerMillion": 60,
      "imageOutputPerMillion": 60,
      "thinkingPerMillion": 60
    }
  }
}

組み込みテーブルにもオーバーライドにも登録されていないモデルでも生成できます。その場合、コストは推測されず、unknown として報告されます。

ツール：generate_image

Parameters

パラメーター	必須	説明
prompt	はい	テキストによる説明または編集指示
images	いいえ	入力画像／参照画像のファイルパスの配列
model	いいえ	Gemini モデル ID
aspectRatio	いいえ	1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、さらに 1:4、4:1、1:8、8:1（gemini-3.1-flash-image）。API によって検証されます。
resolution	いいえ	512（gemini-3.1-flash-image のみ）、1K、2K、4K
outputDir	いいえ	このリクエストの出力ディレクトリを上書きします
filename	いいえ	保存するファイルのベース名（例：hero-banner）。重複した場合は自動的にバージョン番号が付与されます。
subfolder	いいえ	出力ディレクトリ内のサブフォルダー（例：landing-page）
sessionId	いいえ	前回の応答から複数ターンの編集セッションを続行します
seed	いいえ	再現可能な生成のための整数シード
grounding	いいえ	"web" = Google Search によるグラウンディング、"web+image" は画像検索結果も追加します（gemini-3.1-flash-image のみ）。高度な機能を参照してください
useSearchGrounding	いいえ	grounding: "web" の旧式エイリアス
thinkingLevel	いいえ	"MINIMAL"（デフォルト）または "HIGH" — gemini-3.1-flash ファミリーの思考の深さ。高度な機能を参照してください
videos	いいえ	動画から画像への変換用の入力動画ファイルパスの配列（gemini-3.1-flash ファミリー）。高度な機能を参照してください
removeBackground	いいえ	透明な PNG 切り抜きを返します。{ "mode": "auto" } = ローカル AI マット処理（あらゆる被写体に対応。デフォルト）；{ "mode": "chroma" } = グリーンスクリーン；{ "mode": "threshold" } = 白色の除去（線画）。API の追加費用はかかりません

Example Response

{
  "imagePath": "/home/user/gemini-images/hero-banner.png",
  "mimeType": "image/png",
  "model": "gemini-3.1-flash-lite-image",
  "sessionId": "session-1711929600000-a1b2c3",
  "sessionTurn": 1,
  "usage": {
    "promptTokens": 5,
    "outputTokens": 1295,
    "imageTokens": 1290,
    "thinkingTokens": 412,
    "totalTokens": 1712,
    "estimatedCost": "$0.0390",
    "pricingVerifiedDate": "2026-09-16"
  },
  "session": {
    "generationsThisSession": 3,
    "totalCostThisSession": "$0.1161",
    "generationsThisHour": 5,
    "limit": {
      "maxPerHour": 20,
      "maxCostPerHour": 5,
      "remainingThisHour": 15
    }
  }
}

Usage Examples

テキストから画像を生成：

「SaaS のランディングページ向けに、モダンなグラデーションスタイルで 16:9 のヒーロー画像を生成する」

画像編集：

「このスクリーンショットを使って、ヘッダーをダークテーマにデザインし直す」（画像パスを指定）

反復編集（複数ターン）：

画像を生成した後、返された sessionId と「もっとミニマルに」といった調整指示を指定して再度呼び出します。前の画像はコンテキストに保持されます。

出力の整理：

filename: "hero"、subfolder: "landing-page" を指定して「ヒーローバナーを生成する」→ ~/gemini-images/landing-page/hero.png に保存されます

高品質：

「大理石の上に置かれたヘッドフォンのフォトリアルな製品写真、4K」（gemini-3-pro-image を使用）

透明な素材（1 回の呼び出し）：

removeBackground: { "mode": "auto" } を指定して「光沢のある赤いスニーカーの製品写真」を生成する → すぐに配置できる透明な PNG が得られます。ローカル AI マット処理はあらゆる被写体に対応し、グリーンスクリーンは不要です。

ツール：process_image

sharp を使ったローカル画像処理です。無料かつ高速で、API 呼び出しはありません。

Parameters

パラメーター	必須	説明
imagePath	はい	処理する画像ファイルのパス
crop	いいえ	ピクセル寸法、アスペクト比、またはフォーカルポイント戦略で切り抜きます
resize	いいえ	アスペクト比を維持しながら幅／高さを変更します
removeBackground	いいえ	背景を除去します：{ "mode": "auto" }（AI マット処理、あらゆる被写体に対応）、{ "mode": "chroma" }（グリーンスクリーン）、または { "mode": "threshold" }（白色）。color が設定されている場合は chroma、それ以外は threshold がデフォルトです
trim	いいえ	余白や透明な境界を自動的に除去します
format	いいえ	png、jpeg、webp に変換します
quality	いいえ	JPEG／WebP の出力品質（1～100）
filename	いいえ	保存するファイルのベース名。重複した場合は自動的にバージョン番号が付与されます。
subfolder	いいえ	出力ディレクトリ内のサブフォルダー
outputDir	いいえ	出力ディレクトリを上書きします

Crop Options

// Pixel-exact
{"width": 500, "height": 300, "left": 100, "top": 50}

// Aspect ratio (center crop)
{"aspectRatio": "16:9"}

// Focal point — shifts crop to the most interesting region
{"aspectRatio": "16:9", "strategy": "attention"}

// Detail-based — shifts crop to the most detailed region
{"aspectRatio": "16:9", "strategy": "entropy"}

背景除去のオプション

// AI semantic matte — best quality, works on ANY subject
{"mode": "auto"}

// White/light background (threshold)
{"mode": "threshold", "threshold": 240}

// Green screen (chroma key)
{"mode": "chroma", "color": "#00FF00"}

// Any solid colour
{"mode": "chroma", "color": "#0000FF", "tolerance": 60}

mode: "auto" は、被写体を意味的に切り分けるローカルの BiRefNet マットを実行するため、クロマキーでは難しい髪、ガラス、緑色や黄色の被写体にも対応できます。マットエンジンは同梱されていません（基本インストールのサイズを約 65 MB に抑えるためです）。初回の auto 呼び出し時に、サーバーがエンジン（@huggingface/transformers、約 340 MB）と fp16 モデル（約 109 MB）を自動インストールします。1〜2 分ほど一度だけ待つ必要がありますが、その後は追加の API 費用なしでローカル実行されます。自動インストールを無効にするには GEMINI_IMAGE_AUTO_INSTALL=0 を設定します（その場合、auto は手動インストールを促すメッセージとともに画像を返します）。chroma と threshold には追加のものは必要ありません。

クロマキー（mode: "chroma"）は、スムーズステップによる境界のぼかし、色の混入の抑制、5 パスのエッジアンチエイリアスを備えた HSV キーイングを使用します（デフォルトの許容値は 80 です）。AI で生成したグリーンスクリーンには #00FF00 を使用してください。Gemini が生成する色合いに正確に合わせるよりも効果的です。

注： クロマキーは、キー色（緑／黄色）と同じ色の被写体や、透明・反射する被写体（ガラス）を損ないます。緑色のオウムは消えてしまいます。こうした被写体には mode: "auto"（AI マットなら保持できます）を使用するか、キャンバス方式を使ってください。generate_image に単色の背景画像を渡し、適切な照明で被写体を配置するよう Gemini に任せます。ガラスのように真に透明なオブジェクトには、切り抜くのではなく最終的な背景を透過させる必要があるため、キャンバス方式が依然として最適です。

よくあるパイプライン

特定の背景に被写体を配置（キャンバス方式）：

generate_image → "Place a [subject] on this background" with images: [solid colour canvas]

API 呼び出しは 1 回です。クロマキーが苦手とする黄色、緑色、ガラスの被写体に最適です。

透過アセット（1 回の呼び出し）：

generate_image → "A product photo of <subject>" with removeBackground: {mode: "auto"}

API 呼び出し 1 回 → 透過 PNG。ローカル AI マットはどのような被写体にも対応します。（ガラスのように真に透明または反射するオブジェクトには、上記のキャンバス方式が依然として最適です。）

グリーンスクリーンから透過アセットを作成（依存関係なし）：

generate_image → "A product photo on a bright green background"
process_image → removeBackground {mode: "chroma"} + trim

マットモデルを完全に回避できます。高コントラストの被写体や、制限された環境／オフライン環境のマシンに最適です。

生成したロゴからファビコンを作成：

process_image → removeBackground {threshold: 230} + trim + resize {width: 192, height: 192}

写真からソーシャルカードを作成：

process_image → crop {aspectRatio: "16:9", strategy: "attention"} + resize {width: 1200}

ウェブ向けに WebP に変換：

process_image → format: "webp" + quality: 85

高度な機能

これらは generate_image のオプトイン設定です。ほとんどのリクエストでは不要なため、エージェントのコンテキストを小さく保てるよう、ツールスキーマではなくここに記載しています。

動画から画像を生成（videos）

モデルは動画を「見て、理解した内容（被写体、雰囲気、色、動き）をもとに新しい画像を合成」します。フレームをコピーするわけではありません。単にフレームが必要な場合は ffmpeg を使ってください。こちらは映像の「理解」が必要な画像を生成するための機能です。

• YouTube のサムネイル — 「動画を見て、思わずクリックしたくなるサムネイルを作って」（最も代表的な用途です。ぼやけていないフレームを探して動画をスクラブする必要はありません）
• ポスターやカバーアート — ゲームプレイの映像 → キーアート、ライブ録画 → ライブポスター、製品デモ → すっきりとした製品写真
• 要約インフォグラフィック — 「このチュートリアル動画の重要な手順を図にして」
• スタイルを変換した静止画 — ダンス動画を鉛筆スケッチ風にする、自宅で撮影した映像から漫画のコマを作る

{
  "prompt": "A bold movie poster for this video, dramatic typography",
  "videos": ["./clip.mp4"],
  "model": "gemini-3.1-flash-image"
}

• gemini-3.1-flash ファミリー（gemini-3.1-flash-image、gemini-3.1-flash-lite-image）でサポートされています。他のモデルでは拒否されます。
• ローカルファイル（mp4、mov、webm、avi、mpeg、wmv、flv、3gpp）を受け付けます。ファイルごとの最大サイズは 500MB で、1 回の呼び出しにつき最大 3 件です。各動画は Google の Files API にアップロードされ、処理が完了するまでポーリングされ、呼び出しに使用された後、削除されます。動画のトークンは入力としてカウントされます（2 秒のクリップで約 140 トークン）。
• sessionId と併用できません — セッションはテキストと画像のみを対象としており、動画のターンではセッションは作成されません（アップロードされたファイルは呼び出し後に削除されるため、保存されたセッションを再生すると無効な参照が使われます）。
• アップロードとサーバー側の処理は生成呼び出しの前に行われ、動画ごとに 120 秒の処理上限が適用されます。REQUEST_TIMEOUT_MS は生成呼び出し自体にのみ適用されます。
• アップロードする動画に必要な権利を有している必要があります。
• 対象範囲に関する注意：これは動画の入力機能です。動画の生成は別のモデルファミリー（Google の Veo。独自の API 経由でアクセスします）の機能であり、このサーバーの対象範囲外です。

思考の深さ（thinkingLevel）

Gemini 3 のすべての画像モデルは、レンダリングの前に「思考」します。デフォルトの MINIMAL はコストとレイテンシを抑えます。品質が推論に左右されるレンダリングには "HIGH" を使用してください。インフォグラフィック、図、メニュー、密度の高いタイポグラフィ、複数の手順からなる構成などが該当します。

{ "prompt": "An infographic explaining the water cycle with labeled diagrams", "thinkingLevel": "HIGH" }

gemini-3.1-flash ファミリーでサポートされています（API による検証は別途行われます）。設定ファイルの defaults.generate.thinkingLevel でプロジェクトのデフォルトとして設定できます。

画像検索によるグラウンディング（grounding: "web+image"）

grounding: "web" は、最新の Google 検索結果（天気、株価チャート、時事ニュース）をレンダリングの根拠として使用します。"web+image" は gemini-3.1-flash-image 専用で、画像検索の結果も取り込みます。ムードボードやトレンドの参考資料に役立ちます。

グラウンディングを使用すると、レスポンスには grounding オブジェクトが含まれます。内容は、ソースの chunks（URI とタイトル、最大 5 件）、searchQueries、searchEntryPointHtml です。Google の利用規約では、グラウンディングされた結果を表示する際に、検索候補へのエントリーポイントを表示することが義務付けられています — searchEntryPointHtml をユーザーに渡してください。これは Google がこの目的のために提供する、レンダリング可能な HTML です。

gemini-3.1-flash-lite-image ではサポートされていません（API によってグラウンディングが拒否されます）。

モデル

モデル	強み	解像度	備考
gemini-3.1-flash-lite-image	最安（約$0.034/画像）、動画入力	1K	デフォルト（Nano Banana 2 Lite）。検索によるグラウンディングには非対応です。参照画像は最大14枚まで使用できますが、複数画像や複数ターンの編集には最適化されていません。その場合は3.1-flashを推奨します
gemini-3.1-flash-image	高速かつ高品質、検索によるグラウンディング（ウェブ＋画像）、動画入力	512、1K、2K、4K	約$0.07/1K画像。オブジェクト参照画像は最大10枚、キャラクター参照画像は最大4枚、スタイル参照画像は最大3枚まで使用できます
gemini-3-pro-image	最高品質、テキスト描画	1K、2K、4K	約$0.13/1K画像。オブジェクト参照画像は最大6枚、キャラクター参照画像は最大5枚まで使用できます
gemini-2.5-flash-image	レガシー	1K	2026-10-02に終了します

廃止された-preview ID（gemini-3-pro-image-preview、gemini-3.1-flash-image-preview）は、APIキーのモデル一覧に表示されることがありますが、2026-06-25に廃止されています。上記のGA IDを使用してください。サーバーは起動時にAPIキーがサポートする画像モデルを検出し、各リクエストをその時点の一覧に照らして検証するため、新しいモデルも更新なしで使用できます。

開発

bun install
bun run build     # TypeScript -> dist/
bun run dev       # Run directly with Bun

ライセンス

MIT