nanobanana-mcp

@nanobanana/mcp 🍌

一个精简的 MCP 服务，用于 Google 的 Nano Banana（Gemini）图像模型和 Veo 视频模型。它可以通过任何 MCP 客户端（Claude Code、Claude Desktop、Cursor）生成和编辑图像，以及生成视频，并返回文件路径而非 base64，从而保持 Agent 的上下文精简。

• 只有六种工具：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 会显示你的密钥实际可用的模型。
• 多图编辑：传入参考图像，用于风格迁移、角色塑造或合成
• 可控制宽高比（从 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

也已作为 io.github.getjoystick/nanobanana-mcp 收录在 MCP Registry 中。

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

参数	必填	描述
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

参数相同，另加：

参数	必填	描述
images	✅	输入文件路径：png、jpg、webp、heic 或 pdf。第一个文件是底图，其余文件是参考图。

这两种工具都会将文件保存到磁盘并返回文件路径。

list_models

不接受参数。分两个部分列出你的 API 密钥可用的图像和视频模型 ID。当固定的模型 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 秒超时限制内所能容纳的最长时间）。立即调用它，并在返回后马上再次调用；无需在两次调用之间暂停，这一点很重要，因为 Agent 无法休眠。

任务 ID 包含服务所需的所有信息，因此即使服务进程在此期间重启，它仍然有效。请及时下载：Google 会在约 2 天后删除服务器端生成的视频，而服务器端副本是 extend_video 唯一可以延长的视频，因此如果你打算续拍，请保留 Veo URI。

要为刚生成的图像添加动画？请先为 generate_image 设置 aspectRatio 为 16:9 或 9:16。Veo 只输出这两种宽高比，并会裁剪你提供的画面，因此方形图像会丢失边缘；无论如何，你都要为视频片段付费。

generate_video

参数	必填	描述
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 秒，从最后一秒继续。输入最长约 141 秒，最多扩展 20 次后，输出最长约 148 秒，且始终为 720p。Lite 不支持。 扩展操作在 Google 保存的视频副本上运行，而非本地文件 — 请传入 get_video_result 输出的 Veo URI。它会在视频约 2 天后过期。

参数	必填	描述
prompt	✅	接下来发生的内容
video	✅	get_video_result 返回的 Veo URI（https:// URI，而非文件路径）
model		Veo 模型 ID（默认 veo-3.1-fast-generate-preview）；Lite 不支持扩展
negativePrompt		不应出现的内容

get_video_result

参数	必填	描述
jobId	✅	generate_video／extend_video 返回的 ID
waitSeconds		此调用阻塞等待任务的时长（默认 45，也是最大值）
outputDir		保存目录（默认 ./nano-banana）
filename		不含扩展名的基本文件名

将完成的视频保存为 .mp4，并返回绝对路径，以及 extend_video 所需的服务端副本 Veo URI。

配置

环境变量	描述
GEMINI_API_KEY	必填。 Gemini API 密钥（也支持 GOOGLE_API_KEY）
NANOBANANA_MODEL	默认图像模型覆盖值
NANOBANANA_VIDEO_MODEL	默认视频模型覆盖值
NANOBANANA_OUTPUT_DIR	默认输出目录覆盖值

模型

模型 ID	说明
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 停用）

视频模型

Veo 没有免费套餐 — 你需要启用结算功能的 API 密钥，并按输出秒数计费。

模型 ID	价格	8 秒片段	说明
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

这三种模型都支持文生视频、图生视频和原生音频。只有 Veo 3.1 和 3.1 Fast 支持扩展、参考图和 4k。片段时长为 4、6 或 8 秒，宽高比为 16:9 或 9:16。

开发

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)

致谢

灵感来自其他 Nano Banana MCP。使用 Claude Code 构建。

许可证

MIT