nano-banana-mcp-s3

Nano-Banana MCP S3 Server 🍌☁️

Enhanced fork with AWS S3 cloud storage support

A Model Context Protocol (MCP) server that provides AI image generation and editing capabilities using Google's Gemini 2.5 Flash Image API with automatic AWS S3 cloud storage integration. Generate stunning images, edit existing ones, and store them directly in your S3 bucket.

✨ Features

• 🎨 Generate Images: Create new images from text descriptions
• ✏️ Edit Images: Modify existing images with text prompts (supports local paths, URLs, and base64)
• 🔄 Iterative Editing: Continue editing the last generated/edited image
• 🖼️ Multiple Reference Images: Use reference images for style transfer and guidance
• ☁️ AWS S3 Integration: Automatic upload to S3 bucket with public URLs
• 🔄 Smart Fallback: Falls back to local storage if S3 is not configured
• 🌐 HTTP Server Mode: Run as REST API for remote access
• 🌍 Cross-Platform: Smart file paths for Windows, macOS, and Linux
• 🔧 Easy Setup: Simple configuration with API key and S3 credentials
• 📁 Auto File Management: Automatic image saving with organized naming

🔑 Setup

• Get your Gemini API key:

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

• 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 S3 Integration (Recommended for cloud storage)

{
  "mcpServers": {
    "nano-banana-s3": {
      "command": "npx",
      "args": ["nano-banana-mcp-s3"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here",
        "S3_BUCKET": "your-bucket-name",
        "S3_REGION": "eu-central-1",
        "S3_ACCESS_KEY_ID": "your-access-key-id",
        "S3_SECRET_ACCESS_KEY": "your-secret-access-key",
        "S3_PUBLIC_URL": "https://your-cloudfront-or-custom-domain.com"
      }
    }
  }
}

Option B: Local storage only (no S3)

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

Note on S3 Configuration:

• If S3 credentials are provided, images will be automatically uploaded to S3
• If S3 is not configured, images will be saved locally (same as original nano-banana-mcp)
• S3_PUBLIC_URL is optional - if not provided, standard S3 URLs will be generated
• S3_SESSION_TOKEN is also supported for temporary AWS credentials

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 S3 Integration

{
  "nano-banana-s3": {
    "command": "npx",
    "args": ["nano-banana-mcp-s3"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here",
      "S3_BUCKET": "your-bucket-name",
      "S3_REGION": "eu-central-1",
      "S3_ACCESS_KEY_ID": "your-access-key-id",
      "S3_SECRET_ACCESS_KEY": "your-secret-access-key"
    }
  }
}

Option B: Local storage only

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

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-s3 using any of these methods:

Configuration Methods

Method A: Environment Variable in MCP Config (Recommended)

{
  "nano-banana-s3": {
    "command": "npx",
    "args": ["nano-banana-mcp-s3"],
    "env": {
      "GEMINI_API_KEY": "your-gemini-api-key-here",
      "S3_BUCKET": "your-bucket-name",
      "S3_REGION": "eu-central-1",
      "S3_ACCESS_KEY_ID": "your-access-key-id",
      "S3_SECRET_ACCESS_KEY": "your-secret-access-key"
    }
  }
}

Method B: System Environment Variable

export GEMINI_API_KEY="your-gemini-api-key-here"
export S3_BUCKET="your-bucket-name"
export S3_REGION="eu-central-1"
export S3_ACCESS_KEY_ID="your-access-key-id"
export S3_SECRET_ACCESS_KEY="your-secret-access-key"
npx nano-banana-mcp-s3

Method C: Using the Configure Tool

npx nano-banana-mcp-s3
# 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"
})

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
})

continue_editing

Continue editing the last generated/edited image.

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

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:

• 🥇 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" }

• 🥈 System Environment Variables

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

• 🥉 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

AWS S3 Storage (Recommended)

When S3 credentials are configured, images are automatically uploaded to your S3 bucket:

• Public URLs are returned immediately after upload
• No local storage required
• Perfect for sharing and cloud-based workflows
• Supports custom CloudFront or CDN URLs via S3_PUBLIC_URL

Local Storage (Fallback)

When S3 is not configured, images are saved locally to platform-appropriate locations:

• Windows: %USERPROFILE%\\Documents\\nano-banana-images\\
• macOS/Linux: ~/nano-banana-images/

File naming convention:

• Generated images: generated-[timestamp]-[id].png
• Edited images: edited-[timestamp]-[id].png
• Custom names: Use the fileName parameter to specify your own names

🎨 Example Workflows

Basic Image Generation

• generate_image - Create your base image
• continue_editing - Refine and improve
• continue_editing - Add final touches

Style Transfer

• generate_image - Create base content
• edit_image - Use reference images for style
• continue_editing - Fine-tune the result

Iterative Design

• generate_image - Start with a concept
• get_last_image_info - Check current state
• continue_editing - Make adjustments
• Repeat until satisfied

🚀 HTTP Server Mode

Run the server as a REST API for remote access:

# Using npm
npm run start:http

# Using environment variables
PORT=3031 HOST=0.0.0.0 GEMINI_API_KEY=your-key npm run start:http

# Development mode
npm run dev:http

Available Endpoints

• GET /health - Health check
• GET /tools - List available MCP tools
• POST /mcp - MCP JSON-RPC endpoint

Docker Deployment

The project includes Docker and AWS ECS configuration for production deployment.

🔧 Development

This project is an enhanced fork with S3 support, built with:

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

Local Development

# Clone the repository
git clone https://github.com/sirio-admin/nano-banana-mcp-s3.git
cd nano-banana-mcp-s3

# Install dependencies
npm install

# Run in development mode (MCP server)
npm run dev

# Run in HTTP server mode
npm run dev:http

# 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

🌟 What's New in nano-banana-mcp-s3

This is an enhanced fork of the original nano-banana-mcp with the following additions:

• ☁️ AWS S3 Integration: Automatic cloud storage with public URLs
• 🌐 HTTP Server Mode: REST API for remote access
• 🔄 Smart Image Loading: Support for URLs and base64 images
• 🐳 Docker Support: Production-ready containerization
• 🚀 ECS Deployment: AWS ECS task definitions included
• 🔐 AWS Secrets Manager: Secure credential management

🤝 Contributing

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

• Original nano-banana-mcp - For the excellent foundation
• Google AI - For the powerful Gemini 2.5 Flash Image API
• Anthropic - For the Model Context Protocol
• AWS - For S3 cloud storage services
• Open Source Community - For the amazing tools and libraries

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: This README and inline code comments
• 💬 Original Project: nano-banana-mcp

☁️ Enhanced with AWS S3 integration by sirio-admin