Skip to content
Back to search

nanobanana-mcp-server

AI image generation MCP server powered by Google Gemini, with smart model selection and 4K output

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhongweili--nanobanana-mcp-server/badge.svg)](/listings/zhongweili--nanobanana-mcp-server)

HTML

<a href="/listings/zhongweili--nanobanana-mcp-server"><img src="/api/listings/zhongweili--nanobanana-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

1. **Google Gemini API Key** - [Get one free here](https://makersuite.google.com/app/apikey) 2. **Python 3.11+** (for development only)

Installation

Option 1: From MCP Registry (Recommended) This server is available in the [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/?q=nanobanana). Search for "nanobanana" or use the MCP name below with your MCP client.

mcp-name: io.github.zhongweili/nanobanana-mcp-server

Option 2: Using `uvx`

uvx nanobanana-mcp-server@latest

Option 3: Using `pip`

pip install nanobanana-mcp-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 532 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Nano Banana MCP Server 🍌
  2. A production-ready **Model Context Protocol (MCP)** server that provides AI-powered image generation capabilities through Google's **Gemini** models with intelligent model selection.
  3. ## ⭐ NEW: Nano Banana 2 — Gemini 3.1 Flash Image! 🍌🚀
  4. **Nano Banana 2** (`gemini-3.1-flash-image-preview`) is now the **default model** — delivering Pro-level quality at Flash speed:
  5. - 🍌 **Flash Speed + 4K Quality**: Up to 3840px at Gemini 2.5 Flash latency
  6. - 🌐 **Google Search Grounding**: Real-world knowledge for factually accurate images
  7. - 🎯 **Subject Consistency**: Up to 5 characters and 14 objects per scene
  8. - ✍️ **Precision Text Rendering**: Crystal-clear text placement in images
  9. - 🏆 **Gemini 3 Pro Image** still available for maximum reasoning depth
  10. <a href="https://glama.ai/mcp/servers/@zhongweili/nanobanana-mcp-server">
  11. <img width="380" height="200" src="https://glama.ai/mcp/servers/@zhongweili/nanobanana-mcp-server/badge" alt="nanobanana-mcp-server MCP server" />
  12. </a>
  13. ## ✨ Features
  14. - 🎨 **Multi-Model AI Image Generation**: Three Gemini models with intelligent automatic selection
  15. - 🍌 **Gemini 3.1 Flash Image (NB2)**: Default model — 4K resolution at Flash speed with grounding
  16. - 🏆 **Gemini 3 Pro Image**: Maximum reasoning depth for the most complex compositions
  17. - ⚡ **Gemini 2.5 Flash Image**: Legacy Flash model for high-volume rapid prototyping
  18. - 🤖 **Smart Model Selection**: Automatically routes to NB2 or Pro based on your prompt
  19. - 📐 **Aspect Ratio Control** ⭐ NEW: Specify output dimensions (1:1, 16:9, 9:16, 21:9, and more)
  20. - 📋 **Smart Templates**: Pre-built prompt templates for photography, design, and editing
  21. - 📁 **File Management**: Upload and manage files via Gemini Files API
  22. - 🔍 **Resource Discovery**: Browse templates and file metadata through MCP resources
  23. - 🛡️ **Production Ready**: Comprehensive error handling, logging, and validation
  24. - ⚡ **High Performance**: Optimized architecture with intelligent caching
  25. ## 🚀 Quick Start
  26. ### Prerequisites
  27. 1. **Google Gemini API Key** - [Get one free here](https://makersuite.google.com/app/apikey)
  28. 2. **Python 3.11+** (for development only)
  29. ### Installation
  30. Option 1: From MCP Registry (Recommended)
  31. This server is available in the [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/?q=nanobanana). Search for "nanobanana" or use the MCP name below with your MCP client.
  32. mcp-name: io.github.zhongweili/nanobanana-mcp-server
  33. Option 2: Using `uvx`
  34. ```bash
  35. uvx nanobanana-mcp-server@latest
  36. ```
  37. Option 3: Using `pip`
  38. ```bash
  39. pip install nanobanana-mcp-server
  40. ```
  41. ## 🔧 Configuration
  42. ### Authentication Methods
  43. Nano Banana supports two authentication methods via `NANOBANANA_AUTH_METHOD`:
  44. 1. **API Key** (`api_key`): Uses `GEMINI_API_KEY`. Best for local development and simple deployments.
  45. 2. **Vertex AI ADC** (`vertex_ai`): Uses Google Cloud Application Default Credentials. Best for production on Google Cloud (Cloud Run, GKE, GCE).
  46. 3. **Automatic** (`auto`): Defaults to API Key if present, otherwise tries Vertex AI.
  47. #### 1. API Key Authentication (Default)
  48. Set `GEMINI_API_KEY` environment variable.
  49. #### 2. Vertex AI Authentication (Google Cloud)
  50. Required environment variables:
  51. - `NANOBANANA_AUTH_METHOD=vertex_ai` (or `auto`)
  52. - `GCP_PROJECT_ID=your-project-id`
  53. - `GCP_REGION=global` (default; required for Gemini 3 Pro Image and NB2. Use `us-central1` only for the legacy 2.5 Flash Image model.)
  54. **Prerequisites**:
  55. - Enable Vertex AI API: `gcloud services enable aiplatform.googleapis.com`
  56. - Grant IAM Role: `roles/aiplatform.user` to the service account.
  57. ### Claude Desktop
  58. #### Option 1: Using Published Server (Recommended)
  59. Add to your `claude_desktop_config.json`:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "nanobanana": {
  64. "command": "uvx",
  65. "args": ["nanobanana-mcp-server@latest"],
  66. "env": {
  67. "GEMINI_API_KEY": "your-gemini-api-key-here"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. #### Option 2: Using Local Source (Development)
  74. If you are running from source code, point to your local installation:
  75. ```json
  76. {
  77. "mcpServers": {
  78. "nanobanana-local": {
  79. "command": "uv",
  80. "args": ["run", "python", "-m", "nanobanana_mcp_server.server"],
  81. "cwd": "/absolute/path/to/nanobanana-mcp-server",
  82. "env": {
  83. "GEMINI_API_KEY": "your-gemini-api-key-here"
  84. }
  85. }
  86. }
  87. }
  88. ```
  89. #### Option 3: Using Vertex AI (ADC)
  90. To authenticate with Google Cloud Application Default Credentials (instead of an API Key):
  91. ```json
  92. {
  93. "mcpServers": {
  94. "nanobanana-adc": {
  95. "command": "uvx",
  96. "args": ["nanobanana-mcp-server@latest"],
  97. "env": {
  98. "NANOBANANA_AUTH_METHOD": "vertex_ai",
  99. "GCP_PROJECT_ID": "your-project-id",
  100. "GCP_REGION": "global"
  101. }
  102. }
  103. }
  104. }
  105. ```
  106. **Configuration file locations:**
  107. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  108. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  109. ### Claude Code (VS Code Extension)
  110. Install and configure in VS Code:
  111. 1. Install the Claude Code extension
  112. 2. Open Command Palette (`Cmd/Ctrl + Shift + P`)
  113. 3. Run "Claude Code: Add MCP Server"
  114. 4. Configure:
  115. ```json
  116. {
  117. "name": "nanobanana",
  118. "command": "uvx",
  119. "args": ["nanobanana-mcp-server@latest"],
  120. "env": {
  121. "GEMINI_API_KEY": "your-gemini-api-key-here"
  122. }
  123. }
  124. ```
  125. ### Cursor
  126. Add to Cursor's MCP configuration:
  127. ```json
  128. {
  129. "mcpServers": {
  130. "nanobanana": {
  131. "command": "uvx",
  132. "args": ["nanobanana-mcp-server@latest"],
  133. "env": {
  134. "GEMINI_API_KEY": "your-gemini-api-key-here"
  135. }
  136. }
  137. }
  138. }
  139. ```
  140. ### OpenAI Codex
  141. Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project-scoped):
  142. ```toml
  143. [mcp_servers.nanobanana]
  144. command = "uvx"
  145. args = ["nanobanana-mcp-server@latest"]
  146. [mcp_servers.nanobanana.env]
  147. GEMINI_API_KEY = "your-gemini-api-key-here"
  148. ```
  149. Or add via the CLI:
  150. ```bash
  151. codex mcp add
  152. ```
  153. Codex supports both the CLI and VSCode extension using the same `config.toml`. Once added, Codex can call `generate_image`, `edit_image`, and `upload_file` tools directly in your coding sessions.
  154. > **Note**: The Codex config file is shared by the CLI and the IDE extension. A TOML syntax error will break both simultaneously, so validate your edits carefully.
  155. ### Continue.dev (VS Code/JetBrains)
  156. Add to your `config.json`:
  157. ```json
  158. {
  159. "mcpServers": [
  160. {
  161. "name": "nanobanana",
  162. "command": "uvx",
  163. "args": ["nanobanana-mcp-server@latest"],
  164. "env": {
  165. "GEMINI_API_KEY": "your-gemini-api-key-here"
  166. }
  167. }
  168. ]
  169. }
  170. ```
  171. ### Open WebUI
  172. Configure in Open WebUI settings:
  173. ```json
  174. {
  175. "mcp_servers": {
  176. "nanobanana": {
  177. "command": ["uvx", "nanobanana-mcp-server@latest"],
  178. "env": {
  179. "GEMINI_API_KEY": "your-gemini-api-key-here"
  180. }
  181. }
  182. }
  183. }
  184. ```
  185. ### Gemini CLI / Generic MCP Client
  186. ```bash
  187. # Set environment variable
  188. export GEMINI_API_KEY="your-gemini-api-key-here"
  189. # Run server in stdio mode
  190. uvx nanobanana-mcp-server@latest
  191. # Or with pip installation
  192. python -m nanobanana_mcp_server.server
  193. ```
  194. ## 🤖 Model Selection
  195. Nano Banana supports three Gemini models with intelligent automatic selection:
  196. ### 🍌 NB2 — Nano Banana 2 (Gemini 3.1 Flash Image) ⭐ DEFAULT
  197. **Flash speed with Pro-level quality — the best of both worlds**
  198. - **Quality**: Production-ready 4K output
  199. - **Resolution**: Up to 4K (3840px)
  200. - **Speed**: ~2-4 seconds per image (Flash-class latency)
  201. - **Special Features**:
  202. - 🌐 **Google Search Grounding**: Real-world knowledge for factually accurate images
  203. - 🎯 **Subject Consistency**: Up to 5 characters and 14 objects per scene
  204. - ✍️ **Precision Text Rendering**: Clear, well-placed text in images
  205. - **Best for**: Almost everything — production assets, marketing, photography, text overlays
  206. - **model_tier**: `"nb2"` (or `"auto"` — NB2 is the auto default)
  207. ### 🏆 Pro Model — Nano Banana Pro (Gemini 3 Pro Image)
  208. **Maximum reasoning depth for the most demanding compositions**
  209. - **Quality**: Highest available
  210. - **Resolution**: Up to 4K (3840px)
  211. - **Speed**: ~5-8 seconds per image
  212. - **Special Features**:
  213. - 🧠 **Advanced Reasoning**: Configurable thinking levels (LOW/HIGH)
  214. - 🌐 **Google Search Grounding**: Real-world knowledge integration
  215. - 📐 **Media Resolution Control**: Fine-tune vision processing detail
  216. - **Best for**: Complex narrative scenes, intricate compositions, maximum reasoning required
  217. - **model_tier**: `"pro"`
  218. ### ⚡ Flash Model (Gemini 2.5 Flash Image)
  219. **Legacy model for high-volume rapid iteration**
  220. - **Speed**: Very fast (2-3 seconds)
  221. - **Resolution**: Up to 1024px
  222. - **Best for**: High-volume generation, quick drafts where 4K is not needed
  223. - **model_tier**: `"flash"`
  224. ### 🤖 Automatic Selection (Recommended)
  225. By default, the server uses **AUTO** mode which routes to **NB2** unless Pro's deeper reasoning is clearly needed:
  226. **Pro Model Selected When**:
  227. - Strong quality keywords: "4K", "professional", "production", "high-res", "HD"
  228. - High thinking level requested: `thinking_level="HIGH"`
  229. - Multi-image conditioning with multiple input images
  230. **NB2 Model Selected When** (default):
  231. - Standard requests, everyday image generation
  232. - Speed keywords: "quick", "draft", "sketch", "rapid"
  233. - High-volume batch generation (`n > 2`)
  234. ### Usage Examples
  235. ```python
  236. # Automatic selection (recommended) — routes to NB2 by default
  237. "A cat sitting on a windowsill" # → NB2 (default)
  238. "Quick sketch of a cat" # → NB2 (speed keyword, NB2 is fast enough)
  239. "Professional 4K product photo" # → Pro (strong quality keywords)
  240. # Explicit NB2 selection
  241. generate_image(
  242. prompt="Product photo on white background",
  243. model_tier="nb2", # Nano Banana 2 (Flash speed + 4K)
  244. resolution="4k",
  245. enable_grounding=True
  246. )
  247. # Leverage Nano Banana Pro for complex reasoning
  248. generate_image(
  249. prompt="Cinematic scene: three characters in a tense standoff at dusk",
  250. model_tier="pro", # Pro for deep reasoning
  251. resolution="4k",
  252. thinking_level="HIGH", # Enhanced reasoning
  253. enable_grounding=True
  254. )
  255. # Legacy Flash for high-volume drafts
  256. generate_image(
  257. prompt="Simple icon",
  258. model_tier="flash" # Fast 1024px generation
  259. )
  260. # Control aspect ratio for different formats ⭐ NEW!
  261. generate_image(
  262. prompt="Cinematic landscape at sunset",
  263. aspect_ratio="21:9" # Ultra-wide cinematic format
  264. )
  265. generate_image(
  266. prompt="Instagram post about coffee",
  267. aspect_ratio="1:1" # Square format for social media
  268. )
  269. generate_image(
  270. prompt="YouTube thumbnail design",
  271. aspect_ratio="16:9" # Standard video format
  272. )
  273. generate_image(
  274. prompt="Mobile wallpaper of mountain vista",
  275. aspect_ratio="9:16" # Portrait format for phones
  276. )
  277. ```
  278. ### 📐 Aspect Ratio Control
  279. Control the output image dimensions with the `aspect_ratio` parameter:
  280. **Supported Aspect Ratios**:
  281. - `1:1` - Square (Instagram, profile pictures)
  282. - `4:3` - Classic photo format
  283. - `3:4` - Portrait orientation
  284. - `16:9` - Widescreen (YouTube thumbnails, presentations)
  285. - `9:16` - Mobile portrait (phone wallpapers, stories)
  286. - `21:9` - Ultra-wide cinematic
  287. - `2:3`, `3:2`, `4:5`, `5:4` - Various photo formats
  288. ```python
  289. # Examples for different use cases
  290. generate_image(
  291. prompt="Product showcase for e-commerce",
  292. aspect_ratio="3:4", # Portrait format, good for product pages
  293. model_tier="pro"
  294. )
  295. generate_image(
  296. prompt="Social media banner for Facebook",
  297. aspect_ratio="16:9" # Landscape banner format
  298. )
  299. ```
  300. **Note**: Aspect ratio works with both Flash and Pro models. For best results with specific aspect ratios at high resolution, use the Pro model with `resolution="4k"`.
  301. ### 📁 Output Path Control ⭐ NEW!
  302. Control where generated images are saved with the `output_path` parameter:
  303. **Three modes of operation:**
  304. 1. **Specific file path** - Save to an exact file location:
  305. ```python
  306. generate_image(
  307. prompt="A beautiful sunset",
  308. output_path="/path/to/sunset.png" # Exact file location
  309. )
  310. ```
  311. 2. **Directory path** - Use auto-generated filename in a specific directory:
  312. ```python
  313. generate_image(
  314. prompt="Product photo",
  315. output_path="/path/to/products/" # Trailing slash indicates directory
  316. )
  317. ```
  318. 3. **Default location** - Uses IMAGE_OUTPUT_DIR or ~/nanobanana-images:
  319. ```python
  320. generate_image(
  321. prompt="Random image"
  322. # output_path defaults to None
  323. )
  324. ```
  325. **Multiple images (n > 1):**
  326. When generating multiple images with a file path, images are automatically numbered:
  327. - First image: `/path/to/image.png`
  328. - Second image: `/path/to/image_2.png`
  329. - Third image: `/path/to/image_3.png`
  330. **Precedence Rules:**
  331. 1. `output_path` parameter (if provided) - highest priority
  332. 2. `IMAGE_OUTPUT_DIR` environment variable
  333. 3. `~/nanobanana-images` (default fallback)
  334. `IMAGE_OUTPUT_DIR` is used only when `output_path` is omitted. A relative `output_path` such as `images/sunset.png` is resolved from the server process working directory, not from `IMAGE_OUTPUT_DIR`. `~/...` expands to the home directory. A trailing slash selects directory mode even when that directory does not exist yet (`outputs/`), and the server creates it and generates the filename.
  335. ```python
  336. # Save to specific location with Pro model
  337. generate_image(
  338. prompt="Professional headshot",
  339. model_tier="pro",
  340. output_path="/Users/me/photos/headshot.png"
  341. )
  342. # Save multiple images to a directory
  343. generate_image(
  344. prompt="Product variations",
  345. n=4,
  346. output_path="/path/to/products/" # Each gets unique filename
  347. )
  348. ```
  349. ## ⚙️ Environment Variables
  350. Configuration options:
  351. ```bash
  352. # Authentication (Required)
  353. # Method 1: API Key
  354. GEMINI_API_KEY=your-gemini-api-key-here
  355. # Method 2: Vertex AI (Google Cloud)
  356. NANOBANANA_AUTH_METHOD=vertex_ai
  357. GCP_PROJECT_ID=your-project-id
  358. GCP_REGION=global # Required for gemini-3-pro-image-preview and NB2; use "us-central1" only for legacy 2.5 Flash Image
  359. # Model Selection (optional)
  360. NANOBANANA_MODEL=auto # Options: flash, nb2, pro, auto (default: auto → nb2)
  361. # Optional
  362. IMAGE_OUTPUT_DIR=/path/to/image/directory # Default: ~/nanobanana-images
  363. GEMINI_BASE_URL=https://custom-api.example.com # Custom API endpoint (for proxies/gateways)
  364. LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR
  365. LOG_FORMAT=standard # standard, json, detailed
  366. ```
  367. ## 🐛 Troubleshooting
  368. ### Common Issues
  369. **"GEMINI_API_KEY not set"**
  370. - Add your API key to the MCP server configuration in your client
  371. - Get a free API key at [Google AI Studio](https://makersuite.google.com/app/apikey)
  372. **"Server failed to start"**
  373. - Ensure you're using the latest version: `uvx nanobanana-mcp-server@latest`
  374. - Check that your client supports MCP (Claude Desktop 0.10.0+)
  375. **"Permission denied" errors**
  376. - The server creates images in `~/nanobanana-images` by default
  377. - Ensure write permissions to your home directory
  378. ### Development Setup
  379. For local development:
  380. ```bash
  381. # Clone repository
  382. git clone https://github.com/zhongweili/nanobanana-mcp-server.git
  383. cd nanobanana-mcp-server
  384. # Install with uv
  385. uv sync
  386. # Set environment
  387. export GEMINI_API_KEY=your-api-key-here
  388. # Run locally
  389. uv run python -m nanobanana_mcp_server.server
  390. ```
  391. ## 📄 License
  392. MIT License - see [LICENSE](LICENSE) for details.
  393. ## 🆘 Support
  394. - **Issues**: [GitHub Issues](https://github.com/zhongweili/nanobanana-mcp-server/issues)
  395. - **Discussions**: [GitHub Discussions](https://github.com/zhongweili/nanobanana-mcp-server/discussions)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.