Ultimate Gemini MCP

Ultimate Gemini MCP

Google の Gemini 3.1 Flash Image 向け MCP サーバーです。高度な推論による高速な画像生成、512px～4K の解像度、最大 14 枚の参照画像、Google 検索によるグラウンディング、自動思考モードに対応しています。

---

セットアップ

Claude Desktop

MCP 設定（mcp.json / .claude.json）に追加します。

{
  "mcpServers": {
    "ultimate-gemini": {
      "command": "uvx",
      "args": ["ultimate-gemini-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

生成されたすべての画像には、真正性と来歴の追跡を目的とした、目に見えない SynthID ウォーターマークが含まれます。

---

機能

Gemini 3.1 Flash Image

• 高解像度出力：512px、1K、2K、4K の解像度
• 高度なテキスト描画：インフォグラフィック、メニュー、図、ロゴに、読みやすくスタイリッシュなテキストを描画
• 最大 14 枚の参照画像：オブジェクト最大 10 個＋キャラクター最大 4 人で、スタイルやキャラクターの一貫性を維持
• Google 検索によるグラウンディング：リアルタイムデータ（天気、株価、イベント、地図）
• Google 画像検索：ウェブ上の画像から視覚的なコンテキストを取得。モデルはあらゆるものの実画像を見つけられます
• 思考モード：推論を設定可能。「minimal」（高速）または「high」（最高品質）
• 透明な背景：フラグを 1 つ切り替えるだけで、すぐに使える透明な PNG/WebP 切り抜きを生成します。実際のアルファチャンネルは、2 パスの差分マット（白背景で生成 → 黒背景に編集 → アルファを解決）で復元します。柔らかなエッジ、グロー、ガラスの表現も忠実に再現し、色のハローは発生しません。必要なのは Pillow のみで、追加の依存関係はありません。モデル呼び出しが 1 回追加されるため、コストは約 2 倍です。
• アプリアイコン／ロゴ専用ツール：generate_app_icon は毎回、正方形、透明背景、1024px の PNG を生成します。長方形や不透明背景のアイコンは生成できません。

このモデルはひと味違います。 学習データだけに頼る従来の画像生成モデルとは異なり、Gemini 3.1 Flash は Google 検索と画像検索にリアルタイムでアクセスできます。商品、人、イベントなど、オンライン上に存在するあらゆるものの実際の参照画像を見つけられます。「Way of Wade 12」と入力すれば実物のシューズを生成し、「Tony Hawk」と入力すれば実際の写真を見つけます。プロンプトを細かく指定しすぎず、モデルに任せてみてください。

サーバー機能

• バッチ処理：複数の画像を並列生成（最大 8 件同時）
• 26 個のエキスパート向けプロンプトテンプレート：写真撮影、シネマティック表現、ストーリーボードなどに対応する MCP スラッシュコマンド
• 柔軟なアスペクト比：14 種類 — 1:1、1:4、1:8、2:3、3:2、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9
• 環境変数で設定可能：出力ディレクトリ、デフォルトサイズ、タイムアウトなど

---

ショーケース

写真のようにリアルな表現

Jensen Huang — GPU サーフィン

Elon Musk — 火星でのチェス対決

Jensen Huang — GPU キッチン

Elon Musk — Cybertruck のシンフォニー

Jensen Huang — 水中データセンター

Elon Musk — SpaceX でスケートボード

Google 検索によるグラウンディング

サンフランシスコの現在の天気

Google 画像検索

花の上の蝶

解像度の違い

512px（最速）

1K

2K

---

クイックスタート

前提条件

• Python 3.11+
• Google Gemini API キー（無料プランを利用できます）

インストール

uvx を使用（推奨 — インストール不要）：

uvx ultimate-gemini-mcp@latest

注： uv が常に PyPI から最新バージョンを取得するように、@latest を使用してください。指定しない場合、uv はキャッシュされた環境を使用することがあります。

pip を使用：

pip install ultimate-gemini-mcp

ソースから：

git clone https://github.com/anand-92/ultimate-image-gen-mcp
cd ultimate-image-gen-mcp
uv sync

設定ファイルの場所：

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

macOS の spawn uvx ENOENT エラー：フルパスを使用してください。which uvx でパスを確認してから、"command": "/Users/you/.local/bin/uvx" を設定します。

Claude Code

claude mcp add ultimate-gemini \
  --env GEMINI_API_KEY=your-api-key \
  -- uvx ultimate-gemini-mcp@latest

Cursor

.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "ultimate-gemini": {
      "command": "uvx",
      "args": ["ultimate-gemini-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

画像はデフォルトで ~/gemini_images に保存されます。保存先を変更するには、"OUTPUT_DIR": "/your/path" を追加します。

---

ツール

generate_image

Gemini 3.1 Flash Image で画像を生成します。

パラメーター	型	デフォルト	説明
prompt	string	必須	テキストによる説明です。簡潔なほうが効果的です。「Tony Hawk kickflip」は、長い説明よりも適しています。検索機能を使えば、モデルが参照情報を自動で見つけられます。
aspect_ratio	string	1:1	次のいずれかです：1:1 1:4 1:8 2:3 3:2 3:4 4:1 4:3 4:5 5:4 8:1 9:16 16:9 21:9
image_size	string	2K	512px、1K、2K、または 4K
output_format	string	png	png、jpeg、または webp
reference_image_paths	list	[]	ローカル画像のパスを最大 14 個指定します（オブジェクト 10 個 + キャラクター 4 人）。
enable_google_search	bool	false	製品、人、イベントなど、現在実在するものにはこれを使用してください。モデルが Google で実際の情報を検索します。
enable_image_search	bool	false	視覚的な参照画像にはこれを使用してください。モデルが制作の参考にする実際の画像を探します。これは非常に便利で、誰や何についても実際の写真を参照できます。
thinking_level	string	minimal	minimal（高速）または high（最高品質）
response_modalities	list	["TEXT","IMAGE"]	["TEXT","IMAGE"]、["IMAGE"]、または ["TEXT"]
transparent_background	bool	false	2 パスの差分マット処理で、背景が透明な PNG/WebP の切り抜きを生成します（コストは約 2 倍です。詳細は下記を参照）。
preserve_original	bool	true	切り抜き画像だけでなく、パス 1 の画像（白背景）も保存します。
alpha_output_format	string	png	アルファチャンネルに対応する出力形式：png または webp

画像サイズの目安：

• 512px — 最速、最低コスト（0.5K）
• 1K — 高速で、テストに適しています（約 1～2 MB）
• 2K — ほとんどの用途におすすめです（約 3～5 MB）
• 4K — 本番用アセットに適した最高品質です（約 8～15 MB）

透明な背景 — フラグを1つ設定するだけで、本物のアルファ切り抜きを取得できます

transparent_background=trueを設定するだけです。 transparent_pathに、そのまま使える透明なPNG/WebP（本物のアルファチャンネル）が返されます。手動でのマスキングも、別のツールも、後続の手順も必要ありません。

アプリアイコンやロゴを生成しますか？専用のgenerate_app_iconツールを使ってください。このツールは、アイコンの制約を誤って設定できないよう、正方形＋透明＋1024pxのPNGを強制します。

内部では、2パス差分マットを使用しています。まず純白（#FFFFFF）の背景で被写体を1回レンダリングし、その画像の背景を純黒（#000000）に編集します。次に2つのフレームを組み合わせ、ピクセルごとのアルファ値を算出します。すべてのチャンネルでobs_white − obs_black = (1−α)·255となるため、α = 1 − mean(obs_white − obs_black)/255です。さらに、黒いフレームから前景色のプリマルチプライを解除します。カラーキーを使わないので、緑のにじみやハローは発生しません。アルファ値は小数を取るため、ソフトエッジ、グロー、ガラス、かすかな影もそのまま残ります。Pillowのみを使用し、MLのダウンロードは不要ですが、モデル呼び出しが2回目に必要です（トークン数／レイテンシは約2倍）。

この手法は、編集パスで背景のみが変更されることを前提としています。パス間でモデルが被写体をずらすと、マットの品質が低下します。その場合も結果は返されます（aligned／alignment_errorで判別でき、post_processing_warningsに目立つ警告が追加されます）。再生成するかどうかは、ご自身で判断できます。

返される各画像には、transparent_path、background_removed、background_removal_mode（"difference_matte"）、aligned、alignment_error、alpha_output_format、post_processing_warningsが追加されます。デフォルトでは、切り抜きとともにパス1（白背景）の元画像も保持されます（preserve_original=true）。

// generate_image(prompt="a friendly robot mascot", transparent_background=true)
{
  "images": [{
    "path": "/path/to/a-friendly-robot-mascot-...png",            // pass-1 (white bg)
    "transparent_path": "/path/to/a-friendly-robot-mascot-...-transparent.png",
    "background_removed": true,
    "background_removal_mode": "difference_matte",
    "aligned": true,
    "alignment_error": 0.004,
    "alpha_output_format": "png",
    "post_processing_warnings": []
  }]
}

エッジがくっきりした被写体や、ソフトなグロー／ガラスの表現に優れています。唯一の失敗要因は、編集パスで被写体がずれること（aligned: falseで通知）です。エッジにゴーストが見える場合は再生成してください。

---

generate_app_icon

アプリアイコンやロゴに特化したツールです。正方形、透明、1024pxが強制されます。誤った値を設定する可能性のあるaspect_ratio、image_size、output_format、transparent_backgroundのパラメーターはありません。すべての結果は、本物のアルファチャンネルを持つPNGとしてtransparent_pathに出力されます。そのまま.iconsetディレクトリに配置し、iconutil -c icnsで変換できます。

パラメーター	型	デフォルト	説明
prompt	string	必須	アイコン／ロゴのマークだけを説明してください。フレーミングと透明化はツールが処理します
reference_image_paths	str | list	null	ブランド／スタイルの参考画像のパス（最大14件）
enable_google_search	bool	false	実際のウェブ上の参考情報をもとにデザインを作成します
enable_image_search	bool	false	視覚的なコンテキストのためにGoogle画像検索を使用します
thinking_level	string	high	minimalまたはhigh（アイコンにはhighがおすすめです）
allow_icon_words_in_prompt	bool	false	例外設定です。「logo」のような単語が本当に被写体の一部である場合に限り、プロンプトの制約を回避します

promptでは、被写体だけを説明してください。成果物については説明しないでください。 このツールは、説明された内容をアイコンにするため、「app icon」、「logo」、「favicon」、「squircle」のようなフレーミングを示す単語はプロンプトで拒否されます（その単語が描かれる被写体に文字どおり含まれる場合に限り、allow_icon_words_in_prompt=trueを設定してください）。正しい例："a glowing electric-blue magnifying glass over a network graph"。誤った例："an app icon of a magnifying glass"。

// generate_app_icon(prompt="a glowing electric-blue magnifying glass over a network graph")
{
  "images": [{
    "transparent_path": "/path/to/...-transparent.png",  // square, 1024px, alpha
    "background_removed": true,
    "alpha_output_format": "png"
  }]
}

---

batch_generate

複数の画像を並列で生成します。

パラメーター	型	デフォルト	説明
prompts	list	required	プロンプト文字列のリスト（最大8件）
aspect_ratio	string	1:1	すべての画像に適用するアスペクト比
image_size	string	2K	すべての画像の解像度
output_format	string	png	すべての画像の形式
response_modalities	list	["TEXT","IMAGE"]	すべての画像のモダリティ
batch_size	int	8	同時リクエストの最大数
enable_image_search	bool	false	視覚的なコンテキストとして Google Image Search を使用します
thinking_level	string	minimal	minimal または high
transparent_background	bool	false	すべての画像に2パスの差分マットを適用します（画像ごとにモデル呼び出しが1回追加で必要です）
preserve_original	bool	true	パス1（白背景）の画像も保持します
alpha_output_format	string	png	透明画像の出力形式：png または webp

---

MCP プロンプトテンプレート

Claude Code では、専門家向けのプロンプトテンプレートを26種類、MCP スラッシュコマンドとして利用できます（/ を入力して一覧を表示します）。各テンプレートは、generate_image または batch_generate に直接渡せるように作成されたプロンプトと推奨パラメーターを返します。アプリアイコンやロゴには、専用の generate_app_icon ツールを使用してください。

コマンド	説明	デフォルトのアスペクト比
photography_shot	レンズと照明の仕様を指定したフォトリアルなショット	16:9
cinematic_scene	映画撮影の用語を使った映画のワンシーン	21:9
product_mockup	商用 E コマース向けの商品撮影	1:1 または 4:5
batch_storyboard	複数シーンのストーリーボード → batch_generate を呼び出します	16:9
macro_shot	マイクロスヌート照明による極端なマクロ撮影	1:1
fashion_portrait	ゴボによる影のパターンを使ったエディトリアルファッション	4:5
technical_cutaway	Stephen Biesty スタイルの断面図	3:2、4K、IMAGE のみ
flat_lay	真上から撮影したノルムコア風の写真	1:1
action_freeze	背景にモーションブラーを加えた高速ストロボ撮影	16:9
night_street	実用光源を使ったムーディーな夜の街並み	16:9
drone_aerial	ゴールデンアワーに真上から撮影した空撮	4:5、4K、IMAGE のみ
stylized_3d_render	サブサーフェススキャタリングを使った UE5 スタイルのレンダリング	1:1、IMAGE のみ
sem_microscopy	走査型電子顕微鏡の疑似カラー画像	1:1、IMAGE のみ
double_exposure	シルエットをブレンドした二重露光	2:3、IMAGE のみ
architectural_viz	レイトレーシングによる建築ビジュアライゼーション	3:2、4K
isometric_illustration	正投影のアイソメトリック3Dイラスト	1:1、IMAGE のみ
food_photography	ハイエンドな逆光の料理写真	4:5
motion_blur	後幕シンクロによるスローシャッター撮影の連続写真	16:9
typography_physical	物理的な環境に埋め込まれたテキスト	16:9、4K、IMAGE のみ
retro_futurism	1970年代のカセットフューチャリズム風アナログ SF	4:3、IMAGE のみ
surreal_dreamscape	不可能な物理法則を描いたシュルレアリスムの情景	1:1、IMAGE のみ
character_sheet	ビデオゲームのキャラクターコンセプトアートシート	3:2、4K、IMAGE のみ
pbr_texture	斜光を当てたシームレスな PBR テクスチャマップ	1:1、IMAGE のみ
historical_photo	時代考証に忠実な、フィルムエミュレーションによる写真	4:5
bioluminescent_nature	長時間露光による生物発光のマクロ撮影	1:1
silhouette_shot	シネマティックな純黒のシルエットを捉えたマスターショット	21:9、4K

---

設定

変数	デフォルト	説明
GEMINI_API_KEY	—	必須。 Google Gemini API キー
OUTPUT_DIR	~/gemini_images	画像の保存先ディレクトリ
DEFAULT_IMAGE_SIZE	2K	デフォルトの解像度（1K、2K、4K）
DEFAULT_MODEL	gemini-3-pro-image-preview	デフォルトのモデル
ENABLE_PROMPT_ENHANCEMENT	false	プロンプトをデフォルトで自動拡張します
ENABLE_GOOGLE_SEARCH	false	Google Search のグラウンディングをデフォルトで有効にします
REQUEST_TIMEOUT	60	API のタイムアウト（秒）
MAX_BATCH_SIZE	8	バッチモードでの最大並列リクエスト数
LOG_LEVEL	INFO	ログレベル

---

トラブルシューティング

spawn uvx ENOENT — Claude Desktop が uvx を見つけられません。フルパスを使用してください：

"command": "/Users/yourusername/.local/bin/uvx"

which uvx で確認できます。

GEMINI_API_KEY not found — MCP 設定の env ブロックまたは .env ファイルにキーを設定してください。Google AI Studio で無料のキーを取得できます。

Content blocked by safety filters — センシティブな内容を避けるようにプロンプトを言い換えてください。

Rate limit exceeded — 待ってから再試行するか、API のクォータをアップグレードしてください。

画像が保存されない — OUTPUT_DIR が存在し、書き込み可能であることを確認してください：mkdir -p /your/output/path。

---

ライセンス

MIT — 詳細は LICENSE をご覧ください。

MCP レジストリ

mcp-name: io.github.nikships/ultimate-image-gen-mcp

リンク

• Google AI Studio — API キーを取得
• Gemini API Docs
• Model Context Protocol
• FastMCP