RELATED 01
Nano-Banana MCP Server
Generate and edit images with Google's Gemini 2.5 Flash Image model from any MCP client
235GitHub stars
1.4k/wknpm downloads
28popularity score
Nano Banana MCP Server
Image generation and editing with Google's Gemini image models, saved to local files
By Zhongwei (individual) Python Local · stdio MediaAI and ML
63 popularity score ★ 403 ↓ 14k/mo
Connect your client
Local (PyPI)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
It needs GEMINI_API_KEY. Replace each <NAME> with your value.
Claude CodeTerminal
claude mcp add nano-banana -e GEMINI_API_KEY=<GEMINI_API_KEY> -- uvx nanobanana-mcp-server@latestClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"nano-banana": {
"command": "uvx",
"args": [
"nanobanana-mcp-server@latest"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>"
}
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"nano-banana": {
"command": "uvx",
"args": [
"nanobanana-mcp-server@latest"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>"
}
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"nano-banana": {
"type": "stdio",
"command": "uvx",
"args": [
"nanobanana-mcp-server@latest"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>"
}
}
}
}Codex~/.codex/config.toml
[mcp_servers.nano-banana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]
[mcp_servers.nano-banana.env]
GEMINI_API_KEY = "<GEMINI_API_KEY>"Gemini CLITerminal
gemini mcp add --scope user -e GEMINI_API_KEY=<GEMINI_API_KEY> nano-banana uvx -- nanobanana-mcp-server@latestSettings 10
GEMINI_API_KEY |
Required: Gemini API key; GOOGLE_API_KEY is accepted instead. Not needed when Vertex AI credentials are used. |
|---|---|
NANOBANANA_AUTH_METHOD |
Optional: api_key, vertex_ai or auto (default auto: API key if set, otherwise Vertex AI). |
GCP_PROJECT_ID |
Optional: Google Cloud project for Vertex AI sign-in. |
GCP_REGION |
Optional: Vertex AI region; default global, which NB2 and Pro need. |
NANOBANANA_MODEL |
Optional: Default model tier: auto, nb2, pro or flash (default auto). |
IMAGE_OUTPUT_DIR |
Optional: Folder for generated images (default ~/nanobanana-images). |
RETURN_FULL_IMAGE |
Optional: Return full-resolution images instead of thumbnails (default false). |
GEMINI_BASE_URL |
Optional: Custom API endpoint for a proxy or gateway. |
FASTMCP_TRANSPORT |
Optional: stdio (default) or http; http listens on FASTMCP_HOST and FASTMCP_PORT, 127.0.0.1:9000 by default. |
LOG_LEVEL |
Optional: DEBUG, INFO, WARNING or ERROR. |
What it does
Nano Banana MCP Server is a Python server that sends image requests to Google's Gemini image models and writes the results to disk. A single generate_image tool both creates new pictures from a prompt and edits existing ones: given one input image or a Gemini Files API id it switches to edit mode on its own, and with up to three input images it conditions a new picture on them. It returns a thumbnail to the client by default and keeps the full file on disk.
Three model tiers are available: Gemini 3.1 Flash Image ("nb2", the default), Gemini 3 Pro Image ("pro") and the older Gemini 2.5 Flash Image ("flash"). In auto mode the server picks NB2 unless the prompt or settings point to Pro. Options cover aspect ratio, resolution up to 4K on NB2 and Pro, Google Search grounding, a negative prompt and up to four images per call. It also ships prompt templates for photography, design and editing, and exposes file metadata and templates as MCP resources.
At version 0.4.6 the server registers four tools: generate_image, upload_file, show_output_stats and maintenance (nanobanana_mcp_server/core/server.py). The README tells Codex users they can call an edit_image tool, but no such tool exists; editing goes through generate_image. The code also accepts GOOGLE_API_KEY in place of GEMINI_API_KEY and can serve over HTTP instead of stdio when FASTMCP_TRANSPORT=http is set, binding to 127.0.0.1:9000 unless FASTMCP_HOST or FASTMCP_PORT say otherwise (config/settings.py); the README mentions neither.
What it needs
| Runtime | Python 3.11+ |
|---|
uv (for uvx) or pip with Python 3.11 or later. A Google Gemini API key from Google AI Studio, or a Google Cloud project with the Vertex AI API enabled, Application Default Credentials and the roles/aiplatform.user role, set with NANOBANANA_AUTH_METHOD=vertex_ai and GCP_PROJECT_ID. Gemini image generation is billed by Google according to your key's plan. A writable output folder (by default ~/nanobanana-images).
Limits
It works only with Google's Gemini image models; there is no other provider. The flash tier tops out at 1024px; 4K and 2K need nb2 or pro. generate_image takes up to three local input images and returns at most four images per call (the model may return fewer); prompts are capped at 8192 characters. Responses carry thumbnails unless return_full_image or RETURN_FULL_IMAGE is set, and full 4K images run 3-7 MB each. With Vertex AI, Gemini 3 Pro Image and NB2 need GCP_REGION=global. The README's edit_image tool does not exist at 0.4.6.
Who it suits
It suits someone who already has a Gemini API key or a Google Cloud project and wants an assistant to produce or edit image files on their own machine, for example assets for a project they are coding. Because every request goes to Google and is billed there, it does not fit offline work or a wish to use another image model. Those who want a hosted endpoint rather than a local process could look at nanobananamcp from acedatacloud, which we also list and which offers a hosted address.
Tools 4
generate_image- Create new images from a prompt or edit given ones, with model tier, resolution, aspect ratio, grounding and output path options
upload_file- Upload a local file to the Gemini Files API so later calls can refer to it by id
show_output_stats- Report on the image output folder and recently generated images
maintenance- Clean up expired Files API entries and old local images, check storage quota, tidy the local database; dry run by default