nanobanana-mcp

@nanobanana/mcp 🍌

Google の Nano Banana（Gemini）画像モデルと Veo 動画モデル向けの軽量な MCP サーバーです。あらゆる MCP クライアント（Claude Code、Claude Desktop、Cursor）から画像の生成・編集、動画の生成を行い、base64 ではなくファイルパスを返すため、エージェントのコンテキストを小さく保てます。

• ツールは 6 つだけです：generate_image、edit_image、generate_video、extend_video、get_video_result、list_models
• デフォルトでは Nano Banana 2（gemini-3.1-flash-image）と Veo 3.1 Fast（veo-3.1-fast-generate-preview）を使用します。呼び出しごと、または環境変数でモデルを切り替えられます。固定したモデル ID が古くなった場合、list_models で API キーが実際に使用できるモデルを確認できます。
• 複数画像の編集：スタイル変換、キャラクター、合成用の参照画像を渡せます
• アスペクト比（1:1 から 21:9、最大 1:4 と 8:1）と解像度（512、1K、2K、4K）を指定できます
• インフォグラフィックなど、現実世界の正確さが必要な画像向けに Google Search でグラウンディングできます
• 動画はブロッキング呼び出しではなくジョブとして処理します：生成には 1～6 分かかるため、generate_video はジョブ ID を返し、get_video_result は各クライアントの 60 秒のタイムアウト内でポーリングします
• 安全な出力パス。デスクトップ MCP クライアントがサーバーを / で起動しても、サーバーが / に書き込むことはありません。
• 認証情報は環境変数のみに保存されるため、API キーがチャットのコンテキストを通ることはありません

クイックスタート

aistudio.google.com/apikey で無料の Gemini API キーを取得してください。

Claude Code

claude mcp add nanobanana -e GEMINI_API_KEY=your_key -- npx -y @nanobanana/mcp

MCP Registry では io.github.getjoystick/nanobanana-mcp としても登録されています。

Claude Desktop / Cursor：これを claude_desktop_config.json または .cursor/mcp.json に追加してください。

{
  "mcpServers": {
    "nanobanana": {
      "command": "npx",
      "args": ["-y", "@nanobanana/mcp"],
      "env": { "GEMINI_API_KEY": "your_key" }
    }
  }
}

ツール

generate_image

Param	Required	Description
prompt	✅	画像の説明
model		Gemini 画像モデル ID（デフォルトは gemini-3.1-flash-image）
aspectRatio		1:1、16:9、9:16、21:9、最大 1:4 と 8:1
size		512、1K、2K、または 4K
grounding		事実の正確さを高めるため Google Search でグラウンディングします
thinkingLevel		minimal または high。high は複雑な画像や文字量の多い画像に役立ちます
outputDir		保存先ディレクトリ（デフォルトは ./nano-banana）
filename		拡張子を除くファイル名

edit_image

同じパラメーターに加えて、次のパラメーターを指定します。

Param	Required	Description
images	✅	入力ファイルのパス（png、jpg、webp、heic、または pdf）。最初の画像がベースとなり、残りは参照画像になります。

どちらのツールもファイルをディスクに保存し、ファイルパスを返します。

list_models

パラメーターはありません。API キーで使用できる画像モデルと動画モデルの ID を、2 つのセクションに分けて一覧表示します。固定したモデル ID が使えなくなった場合に便利です。以前の Nano Banana サーバーではこれが原因で問題が起きていました。また、Veo の ID はプレビュー版のため、名称が変更されることがあります。

動画

Veo の生成には 1～6 分かかりますが、MCP クライアントは約 60 秒でツール呼び出しを終了します。そのため、動画はジョブとして処理します。ジョブを開始してから、結果をポーリングしてください。

generate_video   →  "Video job started: <jobId>"
get_video_result →  "Still processing (<jobId>)…"   ← blocks up to 45s, then call again
get_video_result →  "Saved: /path/to/clip.mp4 (veo-3.1-fast-generate-preview)
                     Veo URI (needed for extend_video; expires ~2 days): https://…"

get_video_result が待機処理を行います。各呼び出しは waitSeconds（デフォルトは 45 秒で、クライアントの 60 秒のタイムアウト内に収まる最大値）までブロックします。すぐに呼び出し、戻り次第もう一度呼び出してください。間に待ち時間を入れる必要はありません。エージェントにはスリープする方法がないため、これは重要です。

ジョブ ID にはサーバーが必要とする情報がすべて含まれているため、間にサーバープロセスが再起動しても処理を続けられます。生成した動画は Google によってサーバー側から約 2 日後に削除されるため、速やかにダウンロードしてください。サーバー側のコピーだけが extend_video で延長できる動画なので、ショットを続ける予定がある場合は Veo URI を保存しておいてください。

生成した画像をアニメーション化する場合は、まず generate_image に aspectRatio として 16:9 または 9:16 を指定してください。Veo が出力できるのはこの 2 つの比率だけで、渡したフレームをクロップするため、正方形の画像は端が切れてしまいます。それでもクリップの料金は発生します。

generate_video

Param	Required	Description
prompt	✅	シーン、動き、カメラ、会話や効果音などを指定します。Veo はネイティブ音声を生成します
image		開始フレームとして使用する画像パス（画像から動画への変換）。Veo は画像を aspectRatio に合わせてトリミングするため、16:9 または 9:16 にしてください。
referenceImages		キャラクター／オブジェクト／スタイルの一貫性を保つための画像パスです。asset は最大 3 枚、style は 1 枚のみ指定できます。image との併用不可。Lite ではサポートされていません。
referenceType		asset（キャラクター、オブジェクト、シーン — デフォルト）または style（美的スタイル）
model		Veo モデル ID（デフォルトは veo-3.1-fast-generate-preview）
aspectRatio		16:9 または 9:16
resolution		720p、1080p、または 4k。1080p と 4k には durationSeconds: 8 が必要です
durationSeconds		4、6、または 8。referenceImages または 1080p／4k を使用する場合は 8 にする必要があります
negativePrompt		表示させたくないもの
personGeneration		allow_all（テキストから動画への変換および延長のみ）または allow_adult。画像ベースの生成（image、referenceImages）には allow_adult が必要です。また、EU／UK／CH／MENA では allow_adult のみ使用できます。

フレーム（image、referenceImages）は png または jpg である必要があります。

extend_video

Veo で生成したクリップを約 7 秒延長し、最後の 1 秒から続けます。入力は最大 約 141 秒、出力は最大約 148 秒で、延長は最大 20 回までです。常に 720p です。Lite ではサポートされていません。

延長はローカルファイルではなく、Google 側にある動画のコピーに対して実行されます。get_video_result が出力する Veo URI を渡してください。有効期限は動画と同じで、約 2 日後に切れます。

Param	Required	Description
prompt	✅	次に起こること
video	✅	get_video_result の Veo URI（https:// URI。ファイルパスではありません）
model		Veo モデル ID（デフォルトは veo-3.1-fast-generate-preview）。Lite では延長できません
negativePrompt		表示させたくないもの

get_video_result

Param	Required	Description
jobId	✅	generate_video／extend_video が返す ID
waitSeconds		ジョブの完了を待つ間、この呼び出しをブロックする時間（デフォルトは 45。これが最大値でもあります）
outputDir		保存先ディレクトリ（デフォルトは ./nano-banana）
filename		拡張子を除いたファイル名

完成した動画を .mp4 として保存し、絶対パスと、extend_video で必要となるサーバー側コピーの Veo URI を返します。

Configuration

Env var	Description
GEMINI_API_KEY	必須です。 Gemini API キー（GOOGLE_API_KEY も使用できます）
NANOBANANA_MODEL	デフォルトの画像モデルの上書き
NANOBANANA_VIDEO_MODEL	デフォルトの動画モデルの上書き
NANOBANANA_OUTPUT_DIR	デフォルトの出力ディレクトリの上書き

Models

Model id	Notes
gemini-3.1-flash-image	デフォルト。 Nano Banana 2：4K 出力、テキスト描画に優れています
gemini-3-pro-image	Nano Banana Pro。より深い推論が必要な複雑なシーン向け
gemini-2.5-flash-image	初代 Nano Banana（レガシー。Google は 2026-10-02 に提供を終了します）

Video models

Veo には無料枠がありません。課金が有効な API キーが必要で、出力の秒数に応じて課金されます。

Model id	Price	8s clip	Notes
veo-3.1-fast-generate-preview	$0.10/s	~$0.80	デフォルト。 全機能を備え、コストに対する品質が最も優れています
veo-3.1-generate-preview	$0.40/s	~$3.20	全機能を備え、最も高い忠実度です
veo-3.1-lite-generate-preview	$0.05/s	~$0.40	最も安価です。テキスト／画像から動画への変換のみで、延長と参照画像には非対応、最大 1080p です

3 つすべてのモデルが、テキストから動画への変換、画像から動画への変換、ネイティブ音声に対応しています。延長、参照画像、4k は Veo 3.1 と 3.1 Fast のみで利用できます。クリップの長さは 4、6、または 8 秒で、アスペクト比は 16:9 または 9:16 です。

Development

npm install
npm run build
GEMINI_API_KEY=your_key npm run smoke   # end-to-end test against the live API
GEMINI_API_KEY=your_key SMOKE_VIDEO=1 npm run smoke   # also generates a 4s clip (~$0.20)

Acknowledgements

他の Nano Banana MCP に着想を得ています。Claude Code で構築しました。

License

MIT