ckorhonen/nano-banana

Nano Banana - AI Image Generation via MCP

Generate stunning 4K images, edit photos, and create graphics with perfect text rendering using Google's Gemini image models via MCP. The default model is gemini-3.1-flash-image-preview (Nano Banana 2), launched February 2026.

When to Use

Invoke when user:

• Asks to "generate an image" or "create a picture"
• Wants to "edit this photo" or "modify this image"
• Needs graphics with text (logos, infographics, diagrams)
• Requests "consistent characters" across multiple images
• Says "visualize this" or "make me a [visual thing]"

Prerequisites

1. Gemini API Key

Get a free API key from Google AI Studio:

1. Sign in with Google account
2. Click "Get API Key" → "Create API Key"
3. Copy and save securely

2. MCP Server Setup

Recommended: NanoBanana-MCP (uses Gemini 3.1 Flash Image for highest quality)

# Quick install via Claude Code CLI
claude mcp add nano-banana --env GEMINI_API_KEY=your-key-here -- npx -y nanobanana-mcp

Or add to ~/.claude/settings.json manually:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["-y", "nanobanana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternative: Nano-Banana-MCP by ConechoAI (Gemini 2.0 Flash - faster, lower cost)

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

Once MCP is configured, these tools become available:

Core Tools

| Tool | Purpose | Key Parameters | |------|---------|----------------| | gemini_generate_image | Create new images from text prompts | prompt, model, aspectRatio, imageSize | | gemini_edit_image | Modify existing images with instructions | imagePath, instructions, model | | continue_editing | Refine the last generated image | instructions | | get_image_history | List all generated images in session | - |

Model Options

| Model ID | Description | |----------|-------------| | gemini-3.1-flash-image-preview | Default. Highest quality, 4K support, best text rendering (Nano Banana 2, launched Feb 2026) | | gemini-2.5-flash-image-preview | Fast generation, 1K resolution, good quality (Nano Banana) | | gemini-3-pro-image-preview | Previous-gen Pro model, still high quality (Nano Banana Pro) | | gemini-2.0-flash-exp | Older experimental model; prefer gemini-2.5-flash-image-preview for new work |

Image Size (Gemini 3.1 / 3 only)

| Size | Use Case | |------|----------| | 4K | Final assets, print, marketing materials | | 2K | Balanced quality and speed | | 1K | Fast iteration, prototyping |

Advanced Features

| Feature | Capability | |---------|------------| | 4K Output | Up to 5632×3072 pixels | | Text Rendering | Accurate text in images (signs, labels, UI) | | Multi-Image Composition | Combine up to 14 reference images | | Character Consistency | Maintain same character across 5+ images | | Google Search Grounding | Real-world accurate imagery |

Prompting Best Practices

Structure Your Prompts

[Subject] + [Style] + [Details] + [Technical Specs]

Example:

"A cozy coffee shop interior, watercolor illustration style, warm lighting, wooden furniture, steaming cup on table, 4K resolution, soft morning light through windows"

For Best Results

1. Be Specific - Include colors, materials, lighting, mood
2. Specify Style - "photorealistic", "oil painting", "3D render", "anime"
3. Add Context - Time of day, weather, setting
4. Request Resolution - "4K", "high resolution", "detailed"

Precision Mode (JSON Prompting)

For high-stakes work requiring exact reproducibility, use structured JSON schemas.

When to Activate

Trigger phrases:

• "I need exact control over..."
• "Create a product shot for [brand]..."
• "Generate a UI mockup..."
• "Make an infographic showing..."
• "I want to iterate on just the lighting..."
• "A/B test different versions..."

Three Schema Types

| Type | Use Case | Key Controls | |------|----------|--------------| | marketing_image | Product shots, hero images | subject, props, lighting, camera, brand locks | | ui_builder | App screens, dashboards | tokens, screens, containers, components | | diagram_spec | Flowcharts, infographics | nodes, edges, data constraints |

The Translator Workflow

1. Describe - User explains what they want in plain English
2. Clarify - Claude asks targeted questions for missing fields
3. Generate - Claude outputs structured JSON schema
4. Review - User checks key fields match intent
5. Render - JSON converts to precise prompt for Nano Banana 2
6. Iterate - Modify specific fields, re-render (scoped changes)

Example: Product Shot

User: "I need a hero shot for Aurora Lime seltzer"

Claude asks: "For the Aurora Lime hero shot:

1. Can size? (12oz standard?)
2. Props? (lime slices, ice, condensation?)
3. Background style? (solid color, gradient, bokeh?)
4. Lighting mood? (bright/refreshing or moody/premium?)"

Result: Structured JSON with exact specifications that can be iterated field-by-field.

Scoped Edits (The Key Unlock)

JSON enables changing ONE thing without regenerating everything:

| Change | What Stays Fixed | |--------|------------------| | Swap lighting direction | Subject, props, background | | Try different camera angle | Lighting, props, environment | | Change background color | Subject geometry, lighting setup | | Add/remove props | Everything else |

Reference Docs

• references/json-prompting.md - Full JSON prompting guide
• references/translator-prompt.md - Translator system prompt
• references/schemas/ - Template schemas for each type
• references/examples-json.md - Filled-out examples

Text in Images

Nano Banana 2 excels at text rendering:

"A vintage movie poster for 'COSMIC ADVENTURE' with bold retro typography, starfield background, astronaut silhouette, 1970s sci-fi aesthetic"

Character Consistency

For consistent characters across images:

1. Generate initial character with detailed description
2. Use history:0 reference in subsequent prompts
3. Describe scene changes while referencing original

First: "A young woman with red curly hair, freckles, green eyes, wearing a blue jacket"
Then: "The same woman from history:0, now sitting at a café, reading a book"

Workflow Examples

Basic Image Generation

User: "Create an image of a futuristic city at sunset"

Claude uses: gemini_generate_image
Prompt: "Futuristic cityscape at golden hour sunset, towering glass skyscrapers with holographic advertisements, flying vehicles, warm orange and purple sky, photorealistic, 4K resolution, cinematic lighting"

Photo Editing

User: "Edit this photo to make it look like winter"

Claude uses: gemini_edit_image
Input: [user's image path]
Instructions: "Transform to winter scene: add snow on ground and surfaces, frost on windows, visible breath, overcast sky, cool blue color grading"

Iterative Refinement

User: "Make the lighting warmer"

Claude uses: continue_editing
Instructions: "Adjust lighting to warmer tones, add golden hour glow, enhance orange/yellow highlights, softer shadows"

Output Management

Images save to: ~/Documents/nanobanana_generated/

Naming format: generated-[timestamp]-[id].png

Security Notes

• API keys stored locally in environment variables
• Never committed to version control
• Images processed locally, not stored on external servers
• Use .env files for key management in projects

Model Comparison

| Model | Speed | Quality | Max Res | Cost | Best For | |-------|-------|---------|---------|------|----------| | gemini-3.1-flash-image-preview | Fast | Highest | 4K | ~$0.045/img (1K) | Final assets, print, marketing | | gemini-2.5-flash-image-preview | Fastest | Good | 1K | ~$0.039/img | Prototyping, iteration, drafts | | gemini-3-pro-image-preview | Slower | High | 4K | ~$0.134/img | Previous-gen Pro fallback | | gemini-2.0-flash-exp | Fast | Good | 1K | Low | Legacy; use 2.5-flash-image-preview instead |

Pricing as of March 2026. Free tier (~500 req/day) available via Google AI Studio for all models.

Troubleshooting

| Issue | Solution | |-------|----------| | "API key invalid" | Verify key at AI Studio | | "Rate limited" | Wait 60s, or upgrade API tier | | "MCP not connected" | Restart Claude Code, check config syntax | | "Image not saving" | Check write permissions on output directory |

Integration

Works well with:

• Artifacts Builder - Generate images for HTML artifacts
• Process Mapper - Create diagram visuals
• Research to Essay - Add illustrations to content

References

• references/prompting-guide.md - Detailed prompting techniques
• references/examples.md - Sample prompts by category