NanoBanana MCP

MCP server that brings Gemini's image generation and editing capabilities to Claude Desktop, Claude Code, and Cursor. Supports Nano Banana 2 (Flash) and Nano Banana Pro models.

Features

• Image Generation - Create 2K images from text prompts
• Image Editing - Transform images with natural language instructions
• Session Consistency - Maintain style/character across generations
• Runtime Model Switching - Switch between Flash and Pro models without restart
• Multi-turn Chat - Conversational context with image support

Quick Start

Prerequisites

• Node.js 18+
• Google AI API Key (Get one here)

Add to Claude Code

claude mcp add nanobanana-mcp -- npx -y @ycse/nanobanana-mcp \
  -e "GOOGLE_AI_API_KEY=your_api_key"

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nanobanana-mcp": {
      "command": "npx",
      "args": ["-y", "@ycse/nanobanana-mcp"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key"
      }
    }
  }
}

Add to Cursor

Create or edit .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "nanobanana-mcp": {
      "command": "npx",
      "args": ["-y", "@ycse/nanobanana-mcp"],
      "env": {
        "GOOGLE_AI_API_KEY": "your_api_key"
      }
    }
  }
}

See Cursor MCP Documentation for more details.

Tools

| Tool | Purpose | |------|---------| | set_aspect_ratio | Required. Set aspect ratio before image generation | | set_model | Switch between flash/pro models at runtime | | gemini_generate_image | Generate images from text prompts | | gemini_edit_image | Edit images with natural language | | gemini_chat | Multi-turn conversation with images | | get_image_history | View session image history | | clear_conversation | Reset session context |

set_aspect_ratio (Required)

Must be called before generating or editing images.

Valid ratios: 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9

set_model

Switch models per-session without restarting:

| Value | Model | Description | |-------|-------|-------------| | flash | gemini-3.1-flash-image-preview | Nano Banana 2 - Faster (default) | | pro | gemini-3-pro-image-preview | Nano Banana Pro - Higher quality |

gemini_generate_image

{
  prompt: string;              // Image description
  aspect_ratio?: string;       // Override session ratio
  output_path?: string;        // Save path (default: ~/Documents/nanobanana_generated/)
  conversation_id?: string;    // Session ID
  use_image_history?: boolean; // Use previous images for consistency
  reference_images?: string[]; // Reference images for style
}

gemini_edit_image

{
  image_path: string;          // File path, "last", or "history:N"
  edit_prompt: string;         // Edit instructions
  aspect_ratio?: string;       // Override session ratio
  output_path?: string;        // Save path
  conversation_id?: string;    // Session ID
  reference_images?: string[]; // Style references
}

Slash Commands

Claude Code

npx @ycse/nanobanana-mcp --install-commands claude-code
# Or manually:
# mkdir -p ~/.claude/commands
# cp commands/claude-code/*.md ~/.claude/commands/

Cursor

npx @ycse/nanobanana-mcp --install-commands cursor
# Or manually:
# mkdir -p .cursor/commands
# cp commands/cursor/*.md .cursor/commands/

See Cursor Slash Commands for more details.

Available Commands

/nb-flash  - Switch to Flash model (faster)
/nb-pro    - Switch to Pro model (higher quality)

Usage Examples

Basic Generation

1. Set aspect ratio: set_aspect_ratio("16:9")
2. Generate: "A cyberpunk cityscape at sunset"

Character Consistency

// First image
{ prompt: "A red-hat cat", conversation_id: "cat" }

// Second image - same character
{ prompt: "The cat taking a nap", conversation_id: "cat", use_image_history: true }

Edit with History Reference

// Edit the last generated image
{ image_path: "last", edit_prompt: "Change hat to blue" }

// Edit specific image from history
{ image_path: "history:0", edit_prompt: "Add sunglasses" }

Switch Models Mid-Session

// Start with Flash for quick iterations
set_model({ model: "flash" })
{ prompt: "Draft concept art" }

// Switch to Pro for final render
set_model({ model: "pro" })
{ prompt: "Final polished version", use_image_history: true }

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_AI_API_KEY | Yes | Google AI API key | | NANOBANANA_MODEL | No | Default model (gemini-3.1-flash-image-preview or gemini-3-pro-image-preview) |

Output Location

Generated images save to ~/Documents/nanobanana_generated/:

• Generated: generated_[timestamp].png
• Edited: [original]_edited_[timestamp].png

Development

git clone https://github.com/YCSE/nanobanana-mcp.git
cd nanobanana-mcp
npm install
npm run dev      # Development mode with hot reload
npm run build    # Production build
npm run start    # Run compiled server

Troubleshooting

Image generation fails:

• Verify API key is valid
• Check quota at Google AI Studio
• Ensure set_aspect_ratio was called first

Tools not showing:

1. Restart Claude Desktop/Code
2. Check config file syntax
3. Verify npx -y @ycse/nanobanana-mcp runs without errors

License

MIT

Links

• npm Package
• Report Issues
• MCP Documentation
• Google AI Studio