nanobanana-mcp-server — Claude Code MCP server: image generation
An MCP server that hands your coding agent image generation and editing through Gemini models. Useful when you want pictures without leaving the session.
claude mcp add --env GEMINI_API_KEY=<GEMINI_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> --transport stdio nanobanana-mcp-server -- uvx nanobanana-mcp-serverWhat nanobanana-mcp-server does
The server plugs into Claude, Codex, Cursor, GitHub Copilot, Windsurf, Cline and Zed, exposing three tools to the agent: generate_image, edit_image and upload_file. Requests go to Gemini models, and the server picks which one fits your prompt. The default is gemini-3.1-flash-image-preview — Nano Banana 2, which renders up to 3840px. Gemini 3 Pro Image stays available when a composition needs deeper reasoning, and Gemini 2.5 Flash Image remains as the older fast option.
You get aspect ratio control (1:1, 16:9, 9:16, 21:9 and others), ready-made prompt templates for photography, design and editing, plus file handling through the Gemini Files API. Templates and file metadata show up to the agent as MCP resources. Nothing runs without GEMINI_API_KEY — sort that out first.
Auth is switched with NANOBANANA_AUTH_METHOD. The api_key path uses a Gemini key; vertex_ai goes through Google Cloud Application Default Credentials and needs GCP_PROJECT_ID and GCP_REGION. Set the region to global for Gemini 3 Pro Image and NB2 — us-central1 only works with the legacy 2.5 Flash Image model. The auto mode tries the key first, then Vertex AI. Running from source requires Python 3.11+.
What it helps with
- generate an illustration from a text description inside a session
- touch up an existing image without leaving the editor
- set the aspect ratio to match a layout
- start from a ready prompt template instead of writing one
- upload a file to the Gemini Files API and reference it
Example prompts for the agent
- Generate an image of a cat in a hat, 16:9
- Edit
cover.pngand remove the background - Upload
logo.pngand use it as a reference
How to install nanobanana-mcp-server
Platform CLI
claude mcp add --env GEMINI_API_KEY=<GEMINI_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> --transport stdio nanobanana-mcp-server -- uvx nanobanana-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>
Platform CLI
codex mcp add nanobanana-mcp-server --env GEMINI_API_KEY=<GEMINI_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> -- uvx nanobanana-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>
Config file
{
"mcpServers": {
"nanobanana-mcp-server": {
"command": "uvx",
"args": [
"nanobanana-mcp-server"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>",
"IMAGE_OUTPUT_DIR": "<IMAGE_OUTPUT_DIR>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>
Config file
{
"servers": {
"nanobanana-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"nanobanana-mcp-server"
],
"env": {
"GEMINI_API_KEY": "<GEMINI_API_KEY>",
"IMAGE_OUTPUT_DIR": "<IMAGE_OUTPUT_DIR>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>
Platform CLI
gemini mcp add -e GEMINI_API_KEY=<GEMINI_API_KEY> -e IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> nanobanana-mcp-server uvx nanobanana-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nanobanana-mcp-server <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about nanobanana-mcp-server
How do I install nanobanana-mcp-server in Claude Code?
Run claude mcp add nanobanana-mcp-server -e GEMINI_API_KEY=<GEMINI_API_KEY> -- uvx nanobanana-mcp-server. The second form also sets an output directory: `claude mcp add --env GEMINI_API_KEY=<GEMINI_API_KEY> --env IMAGE_OUTPUT_DIR=<IMAGE_OUTPUT_DIR> --transport stdio nanobanana-mcp-server -- uvx nanobanana-mcp-server`.
What does nanobanana-mcp-server do?
It exposes generate_image, edit_image and upload_file to your agent, backed by Gemini models. The server chooses the model based on your prompt.
What does the server need to run?
Either a GEMINI_API_KEY or Vertex AI access with GCP_PROJECT_ID and GCP_REGION. Pick the method with NANOBANANA_AUTH_METHOD.
