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 APIs. Supports both Gemini 2.5 Flash Image (fast) and Gemini 3 Pro Image (high-resolution up to 4K). Generate stunning images, edit existing ones, and iterate on your creations with simple text prompts.

✨ Features

• 🎨 Generate Images: Create new images from text descriptions
• ✏️ 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
• 📐 Aspect Ratio Control: Support for 10 different aspect ratios (1:1, 4:3, 16:9, etc.)
• 🔍 Resolution Control: Up to 4K resolution with Gemini 3 Pro Image
• 🤖 Model Selection: Choose between fast (Flash) or high-quality (Pro) models
• 🌍 Cross-Platform: Smart file paths for Windows, macOS, and Linux
• 🔧 Easy Setup: Simple configuration with API key and environment variables
• 📁 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": ["@zhibinyang/nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here",
        "GEMINI_IMAGE_MODEL": "gemini-2.5-flash-image"
      }
    }
  }
}

Option B: Without environment variable

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

Usage Examples:

Generate an image of a sunset over mountains

Edit this image to add some birds in the sky

Continue editing to make it more dramatic

🎯 Usage with Cursor

Configuration:

Add to your Cursor MCP configuration:

Option A: With environment variable (Recommended)

{
  "nano-banana": {
    "command": "npx",
    "args": ["@zhibinyang/nano-banana-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here",
      "GEMINI_IMAGE_MODEL": "gemini-2.5-flash-image"
    }
  }
}

Option B: Without environment variable

{
  "nano-banana": {
    "command": "npx",
    "args": ["@zhibinyang/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": ["@zhibinyang/nano-banana-mcp"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here",
      "GEMINI_IMAGE_MODEL": "gemini-2.5-flash-image"
    }
  }
}

Method B: System Environment Variable

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

Method C: Using the Configure Tool

npx @zhibinyang/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.

generate_image({
  prompt: "A futuristic city at night with neon lights",
  aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9", // default: 4:3
  imageSize?: "1K" | "2K" | "4K" // default: 1K, only works with gemini-3-pro
})

edit_image

Edit a specific image file.

edit_image({
  imagePath: "/path/to/image.png",
  prompt: "Add a rainbow in the sky",
  referenceImages?: ["/path/to/reference.jpg"], // optional
  aspectRatio?: "4:3",
  imageSize?: "1K"
})

continue_editing

Continue editing the last generated/edited image.

continue_editing({
  prompt: "Make it more colorful",
  referenceImages?: ["/path/to/style.jpg"], // optional
  aspectRatio?: "4:3",
  imageSize?: "1K"
})

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", "GEMINI_IMAGE_MODEL": "gemini-2.5-flash-image" }

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.

🔧 Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GEMINI_API_KEY | Your Gemini API key (required) | - | | GEMINI_IMAGE_MODEL | Default image generation model | gemini-2.5-flash-image | | NANO_BANANA_OUTPUT_DIR | Custom directory for saving generated images | Platform-specific (see below) |

Available Models:

• gemini-2.5-flash-image - Fast, optimized for speed (1024px output)
• gemini-3-pro-image-preview - High quality, supports up to 4K resolution

📁 File Storage

Images are automatically saved to platform-appropriate locations:

• Custom: Set NANO_BANANA_OUTPUT_DIR environment variable to override default paths
• Windows: %USERPROFILE%\Documents\nano-banana-images\
• macOS/Linux: ./generated_imgs/ (in current directory)
• Fallback: ~/nano-banana-images/ (when run from /, system paths, or temp directories)

💡 Tip for MCP clients: When running via npx in sandboxed environments (like Antigravity), the working directory may be / which is not writable. In such cases, either:

1. Set NANO_BANANA_OUTPUT_DIR to specify a custom output path, or
2. The server will automatically fall back to ~/nano-banana-images/

File naming convention:

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

🎨 Example Workflows

Basic Image Generation

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

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

1. generate_image - Start with a concept
2. get_last_image_info - Check current state
3. continue_editing - Make adjustments
4. Repeat until satisfied

🔧 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 Image APIs
• 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!