gemini

Gemini MCP - Claude 内で Google Gemini の画像生成、動画、検索グラウンディングを利用

この Gemini MCP サーバーを Claude Desktop の環境で使い始めて、もうすぐ1年になります。常にオンにしている数少ないサーバーのひとつです。Gemini が Claude の代わりになるからではありません（なりません）。検索グラウンディング、画像生成、SVG 図、動画は Gemini が得意とする機能であり、ブラウザーのタブを切り替えるよりも、Claude 内のツールとして使えるほうが便利だからです。

実際に多くの人が求めているモデルを中心に、14個のツールを用意しています。画像生成には Nano Banana Pro（gemini-3-pro-image）と Nano Banana 2、音声を同期した動画生成には Veo 3.1、チャットには Gemini 4 Argon、深い調査には Gemini 3.1 Pro を使用します。後者2つはどちらも Google 検索によるグラウンディングに対応しています。生成結果はファイルパスとして表示され、ユーザーが開きに行く必要はありません。MCP Apps を通じて、すべて Claude Desktop 内にインラインでプレビュー表示されます。

npx コマンドを1つ実行するだけです。

初めての方は、完全版ユーザーガイドをご覧ください。すべてのツール、無料枠に関する注意点、問題が起きたときの対処法を説明しています。

---

クイックナビゲーション

生成できるもの | 使い始める | 機能 | 画像出力 | 設定 | ツール | モデル | 要件

---

生成できるもの

以下はすべて、この文章を書いた日の午後に、このリポジトリのツールから出力されたものです。手を加えていません。プロンプトはキャプションに記載しているので、ご自身で確かめてみてください。

検索で情報を補強した画像生成。 use_search=true を指定して generate_image を1回呼び出します。Gemini は実際の英国気象庁の週間予報を検索してから、画像にしました。日付と気温は実際のものです（まあ、予報としての実際ですが）。

プロンプト：「洗練されたエディトリアル調のインフォグラフィックポスター：今週のロンドンの天気。検索で、今後5日間の実際の予報データを使って……」 - gemini-3-pro-image、16:9、2K。

正しいスペルで表示されるテキスト。 これは、以前の世代の画像モデルにはできなかった、Nano Banana Pro の特長です。ここにあるラベルはすべて、モデルがそのまま生成したものです。

プロンプト：「MCPツール呼び出しの仕組み」と題した、4つの番号付きステップからなる、すっきりとした雑誌品質のインフォグラフィック……」 - gemini-3-pro-image。

生成してから編集。 左は generate_image の出力です。右はそのファイルに対し、「コースを日中のモンツァに変え、リムライトを窓からの光に差し替え、ペダルを赤くする」という1文の指示で edit_image を実行したものです。同じコックピット、同じカメラアングルです。

generate_image	edit_image

Veo 3.1による画像から動画への変換。 上の夜のコックピットを firstFrameImage として generate_video に渡しました。生成音声（エンジン音、タイヤの擦過音）付きで、1080pの8秒動画です。下のGIFは無音で、GitHub用に縮小されていますが、実際のファイルはきちんとしたMP4です。

実際に使えるSVG。 図の画像ではなく、ページに埋め込んだり、手作業で編集したり、リポジトリにコミットしたりできる、本物のベクターマークアップです。どちらも、ツールがディスクに書き込んだ未加工の .svg ファイルです。

generate_svg style=technical	generate_svg style=data-viz

段落からランディングページを生成。 概要、会社名、ブランドカラーを指定して generate_landing_page を実行します。HTMLは自己完結型で、CSSはインライン、ヒーロー部分の小さなグラフはアニメーションするSVGです。ファイルをChromeで開いたときのスクリーンショットで、ほかには何も手を加えていません。

そして高速なモデル。 4Kよりも量を重視するときに使う Nano Banana 2（gemini-3.1-flash-image）です。所要時間は約10秒でした。

---

2分で始める

ステップ 1：Gemini API キーを取得する

Google AI Studio にアクセスして作成します。

無料枠について、デフォルト設定では有料モデルが使われるため、説明します。Google の料金ページによると、Gemini 3 Flash Preview には無料枠がありますが、フラッグシップモデルは有料のみです。また、gemini-4-argon は gemini_chat と generate_landing_page のデフォルトで、gemini-3.1-pro-preview は gemini_deep_research（統合）と analyze_image のデフォルトです。無料のキーでは、無料モデルを指定しない限り、これらの呼び出しは失敗します。GEMINI_DEFAULT_MODEL=gemini-3-flash-preview（チャットとランディングページに適用）を設定し、同様に GEMINI_DEEP_RESEARCH_MODEL と GEMINI_IMAGE_ANALYSIS_MODEL を設定するか、各呼び出しで model を渡してください。generate_svg はすでに gemini-3-flash-preview がデフォルトです。Google はこれらの枠を変更するため、他のモデルを使う前に料金ページを確認してください。

ステップ 2：Claude Desktop の設定に追加する

設定ファイルの場所：

• Windows：C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["@houtini/gemini-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

ステップ 3：Claude Desktop を再起動する

これで完了です。ツールは自動的に表示されます。初回実行時に npx がパッケージを取得するため、別途インストールする必要はありません。

代わりにローカルビルドを使う

開発時、または npx に依存したくない場合：

git clone https://github.com/houtini-ai/gemini-mcp
cd gemini-mcp
npm install --include=dev
npm run build

次に、設定でローカルビルドを指定します：

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["C:/path/to/gemini-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code（CLI）

Claude Code は claude_desktop_config.json を読み込みません。代わりに claude mcp add を使います：

claude mcp add -e GEMINI_API_KEY=your-api-key-here -s user gemini -- npx -y @houtini/gemini-mcp

画像と動画の出力ディレクトリを指定する場合：

claude mcp add \
  -e GEMINI_API_KEY=your-api-key-here \
  -e GEMINI_IMAGE_OUTPUT_DIR=/path/to/output \
  -s user \
  gemini -- npx -y @houtini/gemini-mcp

claude mcp get gemini で確認します。Status: Connected と表示されていれば接続されています。

---

できること

Google 検索グラウンディングを使ったチャット

Use gemini:gemini_chat to ask: "What changed in the MCP spec in the last month?"

グラウンディングはデフォルトで有効です。Gemini は回答前に Google を検索するため、学習データのカットオフに基づく推測ではなく、今月の情報を得られます。また、ソースは Markdown のリンクとして返されます。「このコードを説明して」のような純粋な推論を求める質問では、grounding: false を設定します。

特に指定しない限り、gemini-4-argon（Gemini 4 Argon）で実行されます。深さより速度を優先する場合は model: "gemini-3.8-flash"、以前のフラッグシップを使う場合は model: "gemini-3.1-pro-preview" を渡してください。thinking_level は Gemini 3.x と 4 のモデルで使用できます。難しいタスクには high、応答を速くしたい場合は low を指定します。

ディープリサーチ

Use gemini:gemini_deep_research with:
  research_question="What are the current approaches to AI agent memory management?"
  max_iterations=5

グラウンディングされた検索を複数回実行し、その結果をまとめて1つのレポートにします。検索は gemini-3.8-flash の低い思考レベルで実行されます（事実を集めるもので、推論するものではありません）。最後の統合は gemini-3.1-pro-preview の高い思考レベルで実行されます。デフォルトでは検索を2回実行してから統合し、2〜3分で完了します。

この分担は、思った以上に重要です。以前のバージョンではすべてを Pro の最大思考レベルで実行していたため、幅広い質問に対する1回の検索だけで Claude Desktop の4分間のタイムアウトを超えることがありました。Claude Desktop では max_iterations を2または3にしてください。IDE やエージェントフレームワークでは、5〜7にすると統合の質が目に見えて向上します。各検索の方向性を指定したい場合、focus_areas には配列を渡せます。

検索グラウンディングを使った画像生成

Use gemini:generate_image with:
  prompt="Stock price chart showing Apple (AAPL) closing prices for the last 5 trading days"
  use_search=true
  aspectRatio="16:9"

デフォルトのモデルは gemini-3-pro-image です。プレビューを終えた現在は Nano Banana Pro です。読みやすいテキストを描画でき、4K に対応しており、会話形式の編集をサポートする唯一のモデルです。gemini-3.1-flash-image（Nano Banana 2）は高速な選択肢です。品質はそれほど変わらず、時間とコストを大幅に抑えられます。数百枚を生成する場合には、Lite バリアントもあります。

use_search=true を指定すると、Gemini は描画の前に情報を検索します。天気、価格、スポーツの試合結果など、データに基づく画像を安定して生成できます。フル解像度のファイルは常にディスクに保存されます。インラインプレビューは MCP の転送上限に収まるようリサイズされますが、元のファイルは変更されません。

Veo 3.1 による動画生成

Use gemini:generate_video with:
  prompt="A close-up shot of a futuristic coffee machine brewing a glowing blue espresso, steam rising dramatically. Cinematic lighting."
  resolution="1080p"
  durationSeconds=8

Google の Veo 3.1 を使用します。ネイティブ音声と同期した、4〜8 秒のクリップを最大 4K で生成します。Google 側で非同期に処理され、完了まで 2〜5 分かかります。ツールが完了するまでポーリングするため、自分で確認する必要はありません。

知っておくと便利なオプション：

• aspectRatio - 横向きは 16:9、縦向きは 9:16
• generateAudio - デフォルトで有効です。プロンプトに合ったセリフや効果音を生成します
• firstFrameImage - 静止画からアニメーションを生成します（上のコックピットのクリップはこの方法で作成されています）
• referenceImages - キャラクターやスタイルの一貫性を保つため、最大 3 枚指定できます
• sampleCount - 1 回の呼び出しで最大 4 種類のバリエーションを生成します
• seed - 実行ごとに出力を決定的にします
• generateThumbnail - ffmpeg が PATH にあれば、そこからフレームを取り出します
• model - より安価で高速な生成を希望する場合は veo-3.1-lite-generate-preview

SVG の生成

これは過小評価されがちな機能です。出力されるのは図の画像ではなく、SVG マークアップそのものです。コードベースやスライド、ウェブページにそのまま配置でき、ラスタライズによる劣化もなく拡大縮小できます。

Use gemini:generate_svg with:
  prompt="Architecture diagram showing a microservices system with API gateway, three services, and a shared database"
  style="technical"
  width=1000
  height=600

4 つのスタイルがあります：

スタイル	最適な用途
technical	アーキテクチャ図、フローチャート、システムマップ
artistic	イラスト、装飾的なグラフィック、アイコン
minimal	見やすいデータビジュアライゼーション、シンプルなチャート
data-viz	チャート、ダッシュボード、インフォグラフィック

実際の SVG コードが返されます。編集、アニメーション化、埋め込み、コミットが可能です。エクスポートの手順も Figma も必要ありません。

model を指定しない場合は gemini-3-flash-preview で実行されます。高速で、SVG マークアップを十分に扱え、無料枠もあります。有料キーを使用していて、より複雑な図を生成したい場合は、model: "gemini-3.1-pro-preview" を指定してください。

画像の編集と分析

会話形式での編集。 Nano Banana Pro はターン間でコンテキストを保持します。前回の呼び出しの思考シグネチャを渡し直すと、作業中の内容を記憶しています。

Use gemini:edit_image with:
  prompt="Change the colour scheme to blue and green"
  images=[{filePath: "C:/output/gemini-123.png", thoughtSignature: "fromPreviousCall"}]

分析には、用途に応じた 2 つのツールがあります：

• describe_image - gemini-3.8-flash による、一般的な画像の簡単な説明
• analyze_image - gemini-3.1-pro-preview による、構造化された情報抽出と本格的な推論

ローカルファイル：

Use gemini:load_image_from_path with filePath="C:/screenshots/error.png"

または、任意の画像ツールの images 配列に filePath を直接渡せば、サーバーがファイルを読み込みます。これにより、MCP の転送制限を完全に回避できます。

メディア解像度の制御

詳細が不要なタスクでは、トークン使用量を最大 75% 削減できます：

レベル	トークン数	削減率	最適な用途
MEDIA_RESOLUTION_LOW	280	75%	簡単なタスク、一括処理
MEDIA_RESOLUTION_MEDIUM	560	50%	PDF やドキュメント（OCR はこのレベルで飽和します）
MEDIA_RESOLUTION_HIGH	1120	デフォルト	詳細な分析
MEDIA_RESOLUTION_ULTRA_HIGH	2000+	画像ごとに適用	最大限の詳細

PDF の OCR では、MEDIUM を使うと、HIGH の半分のトークン数で同じテキストを抽出できます。異なる結果になるケースは、これまで見つかっていません。

ランディングページの生成

Use gemini:generate_landing_page with:
  brief="A SaaS tool that helps developers monitor API latency"
  companyName="PingWatch"
  primaryColour="#6366F1"
  style="startup"
  sections=["hero", "features", "pricing", "cta"]

単一の自己完結型 HTML ファイルです。CSS はインラインで、JavaScript はバニラ JS を使い、外部依存関係はありません。スタイルは minimal、bold、corporate、startup です。上のギャラリーにある PingWatch のページは、まさにこの呼び出しで生成されています。

プロフェッショナルなチャートデザインシステム

gemini_prompt_assistant には、名前を指定して利用できる 9 つのチャートデザインシステムが用意されています：

システム	インスピレーション	最適な用途
storytelling	Cole Nussbaumer Knaflic	経営層向けプレゼンテーション
financial	Financial Times	エディトリアルジャーナリズム - FT ピンク、セリフ体のタイトル
terminal	Bloomberg / fintech	ネオンカラーを取り入れた、高密度のダークモード
modernist	W.E.B. Du Bois	大胆な幾何学的ブロック、鮮明なコントラスト
professional	IBM Carbon / Tailwind	エンタープライズ向けダッシュボード
editorial	FiveThirtyEight / Economist	データジャーナリズム
scientific	Nature / Science	学術的な厳密さ
minimal	Edward Tufte	データインク比の最大化
dark	Observable	モダンなダークモード

ヘルプシステム

Use gemini:gemini_help with topic="overview"

Claude から離れずに、ドキュメント全体を確認できます。トピック：overview、image_generation、image_editing、image_analysis、chat、deep_research、grounding、media_resolution、models、all。

---

画像の出力と保存

デフォルトでは、画像は Claude 内に直接表示されるインラインプレビューとして返され、フルサイズのファイルはパッケージの隣に保存されます。すべての画像を適切な場所に保存したい場合は、GEMINI_IMAGE_OUTPUT_DIR を設定してください。

"env": {
  "GEMINI_API_KEY": "your-api-key-here",
  "GEMINI_IMAGE_OUTPUT_DIR": "C:/Users/username/Pictures/gemini-output"
}

画像ごとに 2 つのファイルが作成されます。

ファイル	内容
フル解像度	すぐにディスクに保存され、変更されません
プレビュー	インライン転送用にサイズを調整した JPEG で、上限内に収まるように調整されます

Gemini は 2～5 MB の画像を返します。サイズ調整では、各レスポンスの画像以外のオーバーヘッドを測定し、残りのバイナリ予算を算出したうえで、1 MB の MCP 転送上限に収まるまでプレビューを段階的に縮小します（800、600、400、300、200px）。フルサイズの画像は常にディスク上に保存されます。

Claude Desktop のインラインビューアー

画像、SVG、動画、ランディングページの結果はそれぞれ、ズーム、保存先パス、コピーボタンを備えた MCP App ビューアーで開きます。Claude Desktop を使用していて、古いバージョンのビューアーが「Waiting for image...」のまま読み込み続けていた場合、原因はビューアーが読み取る構造化データを Claude Desktop が削除していたことです（ext-apps#696）。2.7.0 以降、ビューアーはサーバーから直接データを取得するため、どちらの方法でも表示されます。

---

設定リファレンス

変数	必須	デフォルト	説明
GEMINI_API_KEY	はい	-	AI Studio の Google AI API キー
GEMINI_DEFAULT_MODEL	いいえ	gemini-4-argon	gemini_chat と generate_landing_page で使用するモデル
GEMINI_DEEP_RESEARCH_MODEL	いいえ	gemini-3.1-pro-preview	gemini_deep_research の統合モデル
GEMINI_DEEP_RESEARCH_SEARCH_MODEL	いいえ	gemini-3.8-flash	gemini_deep_research のグラウンディング検索パスで使用するモデル
GEMINI_IMAGE_ANALYSIS_MODEL	いいえ	gemini-3.1-pro-preview	analyze_image で使用するモデル
GEMINI_IMAGE_DESCRIBE_MODEL	いいえ	gemini-3.8-flash	describe_image で使用するモデル
GEMINI_IMAGE_GENERATION_MODEL	いいえ	gemini-3-pro-image	generate_image と edit_image で使用するモデル
GEMINI_DEFAULT_GROUNDING	いいえ	true	デフォルトで Google Search のグラウンディングを無効にするには、false に設定します
GEMINI_IMAGE_OUTPUT_DIR	いいえ	-	生成した画像と動画の保存先
GEMINI_ALLOW_EXPERIMENTAL	いいえ	false	自動検出に実験版およびプレビュー版モデルを含めます
GEMINI_REQUEST_TIMEOUT_MS	いいえ	240000	チャットおよび分析呼び出しのリクエストごとのタイムアウト（ミリ秒）
GEMINI_MCP_RETRY_ATTEMPTS	いいえ	3	Gemini API リクエストの合計試行回数。一時的なネットワーク障害（fetch failed、ECONNRESET、プロキシや VPN の切断）は、バックオフを伴って再試行されます。1 にすると無効になります
GEMINI_MCP_LOG_FILE	いいえ	false	ログを ~/.gemini-mcp/logs/ に書き込みます
DEBUG_MCP	いいえ	false	ツール呼び出しのデバッグ用に stderr へログを出力します

ツールリファレンス

ツール	説明
gemini_chat	Gemini 4 Argon とチャットします。Google 検索によるグラウンディングはデフォルトで有効です。thinking_level をサポートしています
gemini_deep_research	Flash でグラウンディングされた検索を実行し、3.1 Pro がレポートにまとめます。デフォルトは 2 回です
gemini_list_models	API キーで利用できるモデルをリアルタイムで一覧表示します
gemini_help	Claude を離れることなく、すべてのツールのドキュメントを確認できます
gemini_prompt_assistant	9 種類のチャートデザインシステムを用いた画像生成の専門的なガイダンスを提供します
generate_image	検索によるグラウンディングをオプションで利用して画像を生成します。フル解像度の画像をディスクに保存します
edit_image	自然言語の指示で画像を編集します。思考シグネチャを介して複数ターンにわたり一貫性を保ちます
describe_image	Gemini 3.8 Flash による高速な画像の説明
analyze_image	Gemini 3.1 Pro による構造化された抽出と分析
load_image_from_path	ローカルの画像ファイルを読み込み、任意の画像ツールで使える base64 を返します
generate_video	Veo 3.1 で動画を生成します。ネイティブ音声付きで、4～8 秒、最大 4K に対応します
generate_svg	図、イラスト、アイコン、データビジュアライゼーション向けの本番環境対応 SVG
generate_landing_page	CSS と JS をインラインで含む、自己完結型の HTML ランディングページ
gemini_viewer_payload	内部用です。インラインビューアーが表示データを取得するために使用します。呼び出す必要はありません

---

モデルのリファレンス

2026年9月22日にライブのモデル API と照合しました。gemini_list_models を使うと、現在お使いのキーで利用できるモデルを確認できます。

モデル	使用先	備考
gemini-4-argon	gemini_chat、generate_landing_page	デフォルト。Gemini 4 Argon ― 現在のフラッグシップモデル。有料のみ ― 無料枠なし
gemini-3.1-pro-preview	gemini_deep_research（統合）、analyze_image	これら2つのデフォルト。高い推論能力。有料のみ ― 無料枠なし
gemini-3.8-flash	describe_image、gemini_deep_research（検索パス）	デフォルト。2026年9月時点におけるGoogleのGA主力モデル。速度を重視する場合は、gemini_chat にも適しています
gemini-3-flash-preview	generate_svg	デフォルト。無料枠あり（Googleの料金ページ、2026年9月24日）
gemini-3.7-flash、3.6、3.5、3.5-flash-lite、3.1-flash-lite	任意のテキストツール	以前のGA Flashリリース。すべて利用可能
gemini-3-pro-image	generate_image、edit_image	デフォルト。Nano Banana Pro、GA。4K、実際のテキスト、会話形式の編集に対応
gemini-3.1-flash-image	generate_image、edit_image	Nano Banana 2、GA。Proに迫る品質、Flashの速度と価格
gemini-3.1-flash-lite-image	generate_image	Nano Banana 2 Lite。最速かつ最安
gemini-3-pro-image-preview、nano-banana-pro-preview、gemini-2.5-flash-image	画像ツール	古いIDですが、既存の設定が引き続き機能するよう、現在も利用可能
veo-3.1-generate-preview	generate_video	デフォルト。映画のような映像、ネイティブ音声、最大4Kに対応
veo-3.1-lite-generate-preview	generate_video	同じAPIで、より低価格かつ高速

デフォルト設定の理由。 何度も検討しました。Gemini 3.8 FlashはGA済みでより新しいモデルですが、Googleが最も強力な推論モデルと呼んでいるのは依然として3.1 Proであり、推論こそが gemini_chat とディープリサーチの要です。そのため、これらではProをデフォルトにし、より軽い describe_image の処理にはFlashを採用しています。画像については、Nano Banana Proがプレビュー版を卒業し、品質面での優位性も維持しているため、デフォルトにしています。速度を大幅に優先して、品質を少し妥協する場合はNano Banana 2を選べます。Geminiの新しいOmni動画モデルは別のAPIを使うため、まだ接続されていません。

Gemini 3に関する注意： すべての3.xモデルでは、temperatureが1.0に強制設定されます（Googleの要件です。値を低くするとループが発生します）。thinking_level は gemini_chat に適用されます。

トークン予算： max_tokens のデフォルト値は、ライブのモデル API で報告される各モデルの出力上限です（現在のGemini 3テキストモデルでは65,536。1Mという値は入力コンテキストです）。これは上限であり、消費量ではないため、使わなかった分の余裕に料金はかかりません。4,096未満の値は無視されます。Gemini 3の思考処理では、出力が表示される前に少ない予算を使い切り、タイムアウトとまったく同じ状態に見えるためです。モデルの実際の上限を超える値は、その上限に調整されます。

---

必要条件

• Node.js 20.19+
• Google AI Studio のGemini APIキー
• ffmpeg（任意。動画サムネイル用）

ライセンス

Apache-2.0