Nano-Banana MCP Server 🍌

🤖 This project was entirely generated by Claude Code - an AI coding assistant that can create complete, production-ready applications from scratch.

A Model Context Protocol (MCP) server that provides AI image generation and editing capabilities using Google's Gemini Image API. Choose between Gemini 2.5 Flash for fast generation or Gemini 3 Pro for professional-quality images with advanced reasoning. Generate stunning images, edit existing ones, and iterate on your creations with simple text prompts.

✨ Features

• 🎨 Generate Images: Create new images from text descriptions
• 🚀 Dual Models: Choose between Gemini 2.5 Flash (fast) or Gemini 3 Pro (professional quality)
• 🎯 High Resolution: Generate images at 1K, 2K, or 4K resolution (Gemini 3 Pro)
• ✏️ Edit Images: Modify existing images with text prompts
• 🔄 Iterative Editing: Continue editing the last generated/edited image
• 🖼️ Multiple Reference Images: Use reference images for style transfer and guidance
• 📐 Custom Aspect Ratios: 1:1, 4:3, 3:4, 16:9, 9:16 support
• 🌍 Cross-Platform: Smart file paths for Windows, macOS, and Linux
• 🔧 Easy Setup: Simple configuration with API key
• 📁 Auto File Management: Automatic image saving with organized naming

🔑 Setup

1. Get your Gemini API key:

   • Visit Google AI Studio
   • Create a new API key
   • Copy it for configuration

2. Configure the MCP server: See configuration examples for your specific client below (Claude Code, Cursor, or other MCP clients).

💻 Usage with Claude Code

Configuration:

Add this to your Claude Code MCP settings:

Option A: With environment variable (Recommended - Most Secure)

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

Option B: Without environment variable

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["nano-banana-mcp"]
    }
  }
}

Usage Examples:

Generate an image of a sunset over mountains

Generate a professional 4K marketing banner with "Summer Sale" text using Gemini 3 Pro

Edit this image to add some birds in the sky

Continue editing to make it more dramatic using Gemini 3 Pro at 2K resolution

🎯 Usage with Cursor

Configuration:

Add to your Cursor MCP configuration:

Option A: With environment variable (Recommended)

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

Option B: Without environment variable

{
  "nano-banana": {
    "command": "npx",
    "args": ["nano-banana-mcp"]
  }
}

Usage Examples:

• Ask Cursor to generate images for your app
• Create mockups and prototypes
• Generate assets for your projects

🔧 For Other MCP Clients

If you're using a different MCP client, you can configure nano-banana-mcp using any of these methods:

Configuration Methods

Method A: Environment Variable in MCP Config (Recommended)

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

Method B: System Environment Variable

export GEMINI_API_KEY="your-gemini-api-key-here"
npx nano-banana-mcp

Method C: Using the Configure Tool

npx nano-banana-mcp
# The server will prompt you to configure when first used
# This creates a local .nano-banana-config.json file

🛠️ Available Commands

generate_image

Create a new image from a text prompt.

// Basic usage (uses Gemini 2.5 Flash by default)
generate_image({
  prompt: "A futuristic city at night with neon lights"
})

// Professional quality with Gemini 3 Pro
generate_image({
  prompt: "Professional marketing banner with 'New Product Launch' text",
  model: "gemini-3-pro-image-preview",
  resolution: "4K",
  aspectRatio: "16:9"
})

edit_image

Edit a specific image file.

// Basic editing
edit_image({
  imagePath: "/path/to/image.png",
  prompt: "Add a rainbow in the sky",
  referenceImages: ["/path/to/reference.jpg"] // optional
})

// Professional editing with Gemini 3 Pro
edit_image({
  imagePath: "/path/to/image.png",
  prompt: "Add legible text 'Special Offer' at the top",
  model: "gemini-3-pro-image-preview",
  resolution: "2K",
  aspectRatio: "4:3"
})

continue_editing

Continue editing the last generated/edited image.

// Basic continuation
continue_editing({
  prompt: "Make it more colorful",
  referenceImages: ["/path/to/style.jpg"] // optional
})

// Professional continuation with Gemini 3 Pro
continue_editing({
  prompt: "Enhance the text clarity and add a gradient background",
  model: "gemini-3-pro-image-preview",
  resolution: "4K"
})

get_last_image_info

Get information about the last generated image.

get_last_image_info()

configure_gemini_token

Configure your Gemini API key.

configure_gemini_token({
  apiKey: "your-gemini-api-key"
})

get_configuration_status

Check if the API key is configured.

get_configuration_status()

⚙️ Configuration Priority

The MCP server loads your API key in the following priority order:

1. 🥇 MCP Configuration Environment Variables (Highest Priority)

   • Set in your claude_desktop_config.json or MCP client config
   • Most secure as it's contained within the MCP configuration
   • Example: "env": { "GEMINI_API_KEY": "your-key" }

2. 🥈 System Environment Variables

   • Set in your shell/system environment
   • Example: export GEMINI_API_KEY="your-key"

3. 🥉 Local Configuration File (Lowest Priority)

   • Created when using the configure_gemini_token tool
   • Stored as .nano-banana-config.json in current directory
   • Automatically ignored by Git and NPM

💡 Recommendation: Use Method 1 (MCP config env variables) for the best security and convenience.

📁 File Storage

Images are automatically saved to platform-appropriate locations:

• Windows: %USERPROFILE%\\Documents\\nano-banana-images\\
• macOS/Linux: ./generated_imgs/ (in current directory)
• System directories: ~/nano-banana-images/ (when run from system paths)

File naming convention:

• Generated images: generated-[timestamp]-[id].png
• Edited images: edited-[timestamp]-[id].png

🎨 Example Workflows

Quick Prototyping (Gemini 2.5 Flash)

1. generate_image - Create your base image (fast)
2. continue_editing - Refine and improve
3. continue_editing - Add final touches

Professional Asset Creation (Gemini 3 Pro)

1. generate_image with model: "gemini-3-pro-image-preview" and resolution: "4K" - Create high-quality base
2. continue_editing with Gemini 3 Pro - Add professional text overlays
3. continue_editing - Fine-tune composition and details

Style Transfer

1. generate_image - Create base content
2. edit_image - Use reference images for style
3. continue_editing - Fine-tune the result

Iterative Design with Model Switching

1. generate_image with Gemini 2.5 Flash - Start with a concept (fast iteration)
2. get_last_image_info - Check current state
3. continue_editing with Gemini 3 Pro and resolution: "2K" - Upgrade to professional quality
4. Repeat until satisfied

🎯 Model Selection Guide

Gemini 2.5 Flash Image (gemini-2.5-flash-image-preview)

• Best for: Quick iterations, concept exploration, casual use
• Speed: Fast generation
• Quality: Good quality for most use cases
• Cost: Lower cost per generation

Gemini 3 Pro Image (gemini-3-pro-image-preview)

• Best for: Professional assets, marketing materials, text-heavy designs
• Speed: Slower but more thoughtful generation
• Quality: Superior quality with advanced reasoning
• Resolution: 1K, 2K, or 4K options
• Special capabilities:
  • Legible, stylized text rendering
  • Better composition and detail
  • Advanced multi-image understanding (up to 14 reference images)
• Cost: Higher cost per generation

🔧 Development

This project was created with Claude Code and follows these technologies:

• TypeScript - Type-safe development
• Node.js - Runtime environment
• Zod - Schema validation
• Google GenAI - Image generation API
• MCP SDK - Model Context Protocol

Local Development

# Clone the repository
git clone https://github.com/claude-code/nano-banana-mcp.git
cd nano-banana-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

📋 Requirements

• Node.js 18.0.0 or higher
• Gemini API key from Google AI Studio
• Compatible with Claude Code, Cursor, and other MCP clients

🤝 Contributing

This project was generated by Claude Code, but contributions are welcome! Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Claude Code - For generating this entire project
• Google AI - For the powerful Gemini 2.5 Flash Image API
• Anthropic - For the Model Context Protocol
• Open Source Community - For the amazing tools and libraries

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: This README and inline code comments
• 💬 Discussions: GitHub Discussions

✨ Generated with love by Claude Code - The future of AI-powered development is here!