nano-banana-mcp

Nano Banana MCP server for generating and editing images with Google Gemini. No Gemini CLI required -- just an API key.

Quick Start

1. Get a Gemini API key from Google AI Studio

2. Add to your Claude Code settings (~/.claude/settings.json) or Claude Desktop config:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "@daniel.barta/nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

3. Restart Claude and ask it to generate an image.

Configuration

Environment Variable	Required	Default	Description
GEMINI_API_KEY	Yes	--	Your Google AI API key
GEMINI_MODEL	No	gemini-3.1-flash-image-preview	Gemini model for image generation/editing
GEMINI_DESCRIBE_MODEL	No	gemini-2.5-flash	Gemini model for image description (text-only output)
GEMINI_BASE_URL	No	--	Custom base URL for Gemini API (proxy support)
OUTPUT_DIR	No	~/nano-banana-output	Directory for saved images

Supported Models

Model	Notes
gemini-3.1-flash-image-preview	Default. Latest, fastest
gemini-3-pro-image-preview	Higher quality, slower
gemini-2.5-flash-image	Fast, cost-effective

Tools

generate_image

Generate an image from a text prompt. Supports batch generation (up to 4 images). Response contains a thumbnail preview; full-res image is saved to disk.

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image
aspectRatio	string	No	Aspect ratio (1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9)
size	string	No	Image size (512px, 1K, 2K, 4K)
n	number	No	Number of images to generate (1-4, default 1)
negativePrompt	string	No	Things to exclude from the generated image
systemInstruction	string	No	System instruction to guide the model

edit_image

Edit an existing image based on a text instruction. Supports multi-image input (up to 10 images total). Response contains a thumbnail preview; full-res image is saved to disk.

Parameter	Type	Required	Description
prompt	string	Yes	What to change
filePath	string	Yes	Path to the source image
additionalFilePaths	string[]	No	Additional image paths (up to 9) for multi-image editing
aspectRatio	string	No	Aspect ratio (1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9)
size	string	No	Image size (512px, 1K, 2K, 4K)
negativePrompt	string	No	Things to exclude from the edited image
systemInstruction	string	No	System instruction to guide the model

describe_image

Get a text description of an image.

Parameter	Type	Required	Description
filePath	string	Yes	Path to the image
question	string	No	Specific question about the image
systemInstruction	string	No	System instruction to guide the model

Supported Input Formats

For edit_image and describe_image, the following image formats are supported:

JPEG, PNG, WebP, GIF, BMP, TIFF, SVG, HEIC/HEIF

File Path Resolution

When you provide a file path for editing or describing, the server searches for the file in this order:

1. Absolute path as given
2. Relative to the current working directory
3. Relative to the output directory
4. Basename only in the output directory

Thumbnails

To avoid hitting Claude Code's session file size limits, MCP responses contain thumbnail previews (max 512px, JPEG quality 80, ~20-50KB) instead of full-resolution images. Full-res images are always saved to disk at the path shown in the response metadata.

The first content block in generate/edit responses is a JSON metadata object:

{
  "model": "gemini-3.1-flash-image-preview",
  "count": 1,
  "images": [
    { "filePath": "/Users/you/nano-banana-output/a-cat-1234567890.png", "mimeType": "image/png" }
  ]
}

Development

git clone https://github.com/bartadaniel/nano-banana-mcp.git
cd nano-banana-mcp
npm install
npm run build

Use the local build in your config:

{
  "mcpServers": {
    "nano-banana": {
      "command": "node",
      "args": ["path/to/nano-banana-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Testing

npm test

Runs unit tests using Node.js built-in test runner (node:test). Tests cover error classes, all documented Gemini API response codes (BlockedReason, FinishReason), config shapes, image extraction edge cases, file operations, path security, and thumbnail generation.

License

MIT