io.github.getjoystick/nanobanana-mcp

@nanobanana/mcp 🍌

A lean MCP server for Google's Nano Banana (Gemini) image models and Veo video models. It generates and edits images and generates video from any MCP client (Claude Code, Claude Desktop, Cursor) and hands back file paths instead of base64, so your agent's context stays small.

• Six tools and nothing else: generate_image, edit_image, generate_video, extend_video, get_video_result, list_models
• Defaults to Nano Banana 2 (gemini-3.1-flash-image) and Veo 3.1 Fast (veo-3.1-fast-generate-preview). Switch models per call or via env. If a pinned model id ever goes stale, list_models shows what your key can actually use.
• Multi-image editing: pass reference images for style transfer, characters, or compositing
• Control over aspect ratio (1:1 through 21:9, out to 1:4 and 8:1) and resolution (512, 1K, 2K, 4K)
• Google Search grounding for images that need real-world accuracy, like infographics
• Video as a job, not a blocked call: generation takes 1–6 min, so generate_video returns a job id and get_video_result polls within every client's 60s timeout
• Safe output paths. The server never writes to / when a desktop MCP client spawns it there.
• Auth lives in env vars only, so your API key never passes through chat context

Quick start

Get a free Gemini API key at aistudio.google.com/apikey.

Claude Code

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

Also listed in the MCP Registry as io.github.getjoystick/nanobanana-mcp.

Claude Desktop / Cursor: add this to claude_desktop_config.json or .cursor/mcp.json:

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

Tools

generate_image

Param	Required	Description
prompt	✅	Image description
model		Gemini image model id (default gemini-3.1-flash-image)
aspectRatio		1:1, 16:9, 9:16, 21:9, extremes up to 1:4 and 8:1
size		512, 1K, 2K, or 4K
grounding		Ground with Google Search for factual accuracy
thinkingLevel		minimal or high; high helps complex or text-heavy images
outputDir		Save directory (default ./nano-banana)
filename		Base filename without extension

edit_image

Same params, plus:

Param	Required	Description
images	✅	Input file path(s): png, jpg, webp, heic, or pdf. The first is the base; the rest are references.

Both tools save to disk and return the file path.

list_models

Takes no params. Lists the image and video model ids your API key can use, in two sections. Handy when a pinned model id stops working, which is how earlier Nano Banana servers broke — and Veo's ids are previews that will be renamed.

Video

Veo generation takes 1–6 minutes, and MCP clients kill a tool call at ~60s. So video is a job: you start one, then poll.

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 does the waiting for you — each call blocks up to waitSeconds (45 by default, the most that fits inside a client's 60s timeout). Call it right away and call it again the moment it returns; there is no need to pause in between, which matters because an agent has no way to sleep.

The job id carries everything the server needs, so it keeps working even if the server process restarts in between. Download promptly: Google deletes generated videos server-side after ~2 days — and that server-side copy is the only thing extend_video can extend, so keep the Veo URI if you plan to continue the shot.

Animating an image you just generated? Give generate_image an aspectRatio of 16:9 or 9:16 first. Veo only outputs those two ratios and crops the frame you hand it, so a square image loses its edges — and you pay for the clip either way.

generate_video

Param	Required	Description
prompt	✅	Scene, motion, camera, and any dialogue or SFX — Veo generates native audio
image		Image path used as the starting frame (image-to-video). Veo crops it to aspectRatio, so make it 16:9 or 9:16.
referenceImages		Image paths for character/object/style consistency: up to 3 for asset, only 1 for style. Not combinable with image; not supported by Lite.
referenceType		asset (characters, objects, scenes — default) or style (aesthetics)
model		Veo model id (default veo-3.1-fast-generate-preview)
aspectRatio		16:9 or 9:16
resolution		720p, 1080p, or 4k; 1080p and 4k require durationSeconds: 8
durationSeconds		4, 6, or 8; must be 8 with referenceImages or 1080p/4k
negativePrompt		What should not appear
personGeneration		allow_all (text-to-video and extension only) or allow_adult. Image-based generation — image, referenceImages — requires allow_adult, and EU/UK/CH/MENA accept only allow_adult.

Frames (image, referenceImages) must be png or jpg.

extend_video

Extends a Veo-generated clip by ~7s, continuing from its final second. Input up to ~141s, output up to ~148s across at most 20 extensions, always 720p. Not supported by Lite.

Extension runs on Google's copy of the video, not on your local file — pass the Veo URI that get_video_result prints. It expires with the video after ~2 days.

Param	Required	Description
prompt	✅	What happens next
video	✅	The Veo URI from get_video_result (an https:// URI, not a file path)
model		Veo model id (default veo-3.1-fast-generate-preview); Lite cannot extend
negativePrompt		What should not appear

get_video_result

Param	Required	Description
jobId	✅	The id returned by generate_video / extend_video
waitSeconds		How long this call blocks waiting for the job (default 45, which is also the max)
outputDir		Save directory (default ./nano-banana)
filename		Base filename without extension

Saves the finished video as .mp4 and returns the absolute path, plus the Veo URI of the server-side copy that extend_video needs.

Configuration

Env var	Description
GEMINI_API_KEY	Required. Gemini API key (GOOGLE_API_KEY also works)
NANOBANANA_MODEL	Default image model override
NANOBANANA_VIDEO_MODEL	Default video model override
NANOBANANA_OUTPUT_DIR	Default output directory override

Models

Model id	Notes
gemini-3.1-flash-image	Default. Nano Banana 2: 4K output, strong text rendering
gemini-3-pro-image	Nano Banana Pro, for complex scenes that need deeper reasoning
gemini-2.5-flash-image	The original Nano Banana (legacy; Google retires it 2026-10-02)

Video models

Veo has no free tier — you need a billing-enabled API key, and you are charged per second of output.

Model id	Price	8s clip	Notes
veo-3.1-fast-generate-preview	$0.10/s	~$0.80	Default. Full feature set; best quality-per-dollar
veo-3.1-generate-preview	$0.40/s	~$3.20	Full feature set; highest fidelity
veo-3.1-lite-generate-preview	$0.05/s	~$0.40	Cheapest; text- and image-to-video only — no extension, no reference images, 1080p max

All three do text-to-video, image-to-video, and native audio. Extension, reference images, and 4k are Veo 3.1 and 3.1 Fast only. Clips are 4, 6, or 8 seconds, in 16:9 or 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

Inspired by other Nano Banana MCPs. Built with Claude Code.

License

MIT