{
  "markdown": "# @nanobanana/mcp 🍌\n\nA lean [MCP](https://modelcontextprotocol.io) 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.\n\n- Six tools and nothing else: `generate_image`, `edit_image`, `generate_video`, `extend_video`, `get_video_result`, `list_models`\n- 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.\n- Multi-image editing: pass reference images for style transfer, characters, or compositing\n- Control over aspect ratio (`1:1` through `21:9`, out to `1:4` and `8:1`) and resolution (`512`, `1K`, `2K`, `4K`)\n- Google Search grounding for images that need real-world accuracy, like infographics\n- 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\n- Safe output paths. The server never writes to `/` when a desktop MCP client spawns it there.\n- Auth lives in env vars only, so your API key never passes through chat context\n\n## Quick start\n\nGet a free Gemini API key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).\n\n**Claude Code**\n\n```bash\nclaude mcp add nanobanana -e GEMINI_API_KEY=your_key -- npx -y @nanobanana/mcp\n```\n\nAlso listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.getjoystick/nanobanana-mcp`.\n\n**Claude Desktop / Cursor**: add this to `claude_desktop_config.json` or `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nanobanana/mcp\"],\n      \"env\": { \"GEMINI_API_KEY\": \"your_key\" }\n    }\n  }\n}\n```\n\n## Tools\n\n### `generate_image`\n\n| Param | Required | Description |\n|---|---|---|\n| `prompt` | ✅ | Image description |\n| `model` | | Gemini image model id (default `gemini-3.1-flash-image`) |\n| `aspectRatio` | | `1:1`, `16:9`, `9:16`, `21:9`, extremes up to `1:4` and `8:1` |\n| `size` | | `512`, `1K`, `2K`, or `4K` |\n| `grounding` | | Ground with Google Search for factual accuracy |\n| `thinkingLevel` | | `minimal` or `high`; `high` helps complex or text-heavy images |\n| `outputDir` | | Save directory (default `./nano-banana`) |\n| `filename` | | Base filename without extension |\n\n### `edit_image`\n\nSame params, plus:\n\n| Param | Required | Description |\n|---|---|---|\n| `images` | ✅ | Input file path(s): png, jpg, webp, heic, or pdf. The first is the base; the rest are references. |\n\nBoth tools save to disk and return the file path.\n\n### `list_models`\n\nTakes no params. Lists the image and video model ids your API key can use, in two\nsections. Handy when a pinned model id stops working, which is how earlier Nano\nBanana servers broke — and Veo's ids are previews that will be renamed.\n\n## Video\n\nVeo generation takes 1–6 minutes, and MCP clients kill a tool call at ~60s. So video\nis a **job**: you start one, then poll.\n\n```\ngenerate_video   →  \"Video job started: <jobId>\"\nget_video_result →  \"Still processing (<jobId>)…\"   ← blocks up to 45s, then call again\nget_video_result →  \"Saved: /path/to/clip.mp4 (veo-3.1-fast-generate-preview)\n                     Veo URI (needed for extend_video; expires ~2 days): https://…\"\n```\n\n`get_video_result` does the waiting for you — each call blocks up to `waitSeconds`\n(45 by default, the most that fits inside a client's 60s timeout). Call it right\naway and call it again the moment it returns; there is no need to pause in between,\nwhich matters because an agent has no way to sleep.\n\nThe job id carries everything the server needs, so it keeps working even if the\nserver process restarts in between. Download promptly: Google deletes generated\nvideos server-side after ~2 days — and that server-side copy is the only thing\n`extend_video` can extend, so keep the Veo URI if you plan to continue the shot.\n\nAnimating an image you just generated? Give `generate_image` an `aspectRatio` of\n`16:9` or `9:16` first. Veo only outputs those two ratios and crops the frame you\nhand it, so a square image loses its edges — and you pay for the clip either way.\n\n### `generate_video`\n\n| Param | Required | Description |\n|---|---|---|\n| `prompt` | ✅ | Scene, motion, camera, and any dialogue or SFX — Veo generates native audio |\n| `image` | | Image path used as the starting frame (image-to-video). Veo crops it to `aspectRatio`, so make it `16:9` or `9:16`. |\n| `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. |\n| `referenceType` | | `asset` (characters, objects, scenes — default) or `style` (aesthetics) |\n| `model` | | Veo model id (default `veo-3.1-fast-generate-preview`) |\n| `aspectRatio` | | `16:9` or `9:16` |\n| `resolution` | | `720p`, `1080p`, or `4k`; 1080p and 4k require `durationSeconds: 8` |\n| `durationSeconds` | | `4`, `6`, or `8`; must be `8` with `referenceImages` or 1080p/4k |\n| `negativePrompt` | | What should not appear |\n| `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`. |\n\nFrames (`image`, `referenceImages`) must be png or jpg.\n\n### `extend_video`\n\nExtends a Veo-generated clip by ~7s, continuing from its final second. Input up to\n~141s, output up to ~148s across at most 20 extensions, always 720p. Not supported\nby Lite.\n\nExtension runs on Google's copy of the video, not on your local file — pass the\n**Veo URI** that `get_video_result` prints. It expires with the video after ~2 days.\n\n| Param | Required | Description |\n|---|---|---|\n| `prompt` | ✅ | What happens next |\n| `video` | ✅ | The Veo URI from `get_video_result` (an `https://` URI, not a file path) |\n| `model` | | Veo model id (default `veo-3.1-fast-generate-preview`); Lite cannot extend |\n| `negativePrompt` | | What should not appear |\n\n### `get_video_result`\n\n| Param | Required | Description |\n|---|---|---|\n| `jobId` | ✅ | The id returned by `generate_video` / `extend_video` |\n| `waitSeconds` | | How long this call blocks waiting for the job (default `45`, which is also the max) |\n| `outputDir` | | Save directory (default `./nano-banana`) |\n| `filename` | | Base filename without extension |\n\nSaves the finished video as `.mp4` and returns the absolute path, plus the Veo URI\nof the server-side copy that `extend_video` needs.\n\n## Configuration\n\n| Env var | Description |\n|---|---|\n| `GEMINI_API_KEY` | **Required.** Gemini API key (`GOOGLE_API_KEY` also works) |\n| `NANOBANANA_MODEL` | Default image model override |\n| `NANOBANANA_VIDEO_MODEL` | Default video model override |\n| `NANOBANANA_OUTPUT_DIR` | Default output directory override |\n\n## Models\n\n| Model id | Notes |\n|---|---|\n| `gemini-3.1-flash-image` | **Default.** Nano Banana 2: 4K output, strong text rendering |\n| `gemini-3-pro-image` | Nano Banana Pro, for complex scenes that need deeper reasoning |\n| `gemini-2.5-flash-image` | The original Nano Banana (legacy; Google retires it 2026-10-02) |\n\n### Video models\n\nVeo has **no free tier** — you need a billing-enabled API key, and you are charged\nper second of output.\n\n| Model id | Price | 8s clip | Notes |\n|---|---|---|---|\n| `veo-3.1-fast-generate-preview` | $0.10/s | ~$0.80 | **Default.** Full feature set; best quality-per-dollar |\n| `veo-3.1-generate-preview` | $0.40/s | ~$3.20 | Full feature set; highest fidelity |\n| `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 |\n\nAll three do text-to-video, image-to-video, and native audio. Extension,\nreference images, and 4k are Veo 3.1 and 3.1 Fast only. Clips are 4, 6, or 8\nseconds, in `16:9` or `9:16`.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nGEMINI_API_KEY=your_key npm run smoke   # end-to-end test against the live API\nGEMINI_API_KEY=your_key SMOKE_VIDEO=1 npm run smoke   # also generates a 4s clip (~$0.20)\n```\n\n## Acknowledgements\n\nInspired by other Nano Banana MCPs. Built with [Claude Code](https://claude.com/claude-code).\n\n## License\n\nMIT\n",
  "bytes": 8411,
  "sha": "1eecdbe1cac54be5108a7f8fff896b3526a0f72a3f549217a7bb95063a8ed818",
  "repo_slug": "getjoystick/nanobanana-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_getjoystick_nanobanana_mcp_d091b073/readme"
}