MCP Banana Image
Generates product images optimized for Amazon, including platform compliance, style presets, and aspect ratios tailored for Amazon listings.
Generates social media images optimized for Instagram, with platform-specific aspect ratios, safe zones, and layouts.
Generates product images optimized for Shopee, with platform compliance, style presets, and aspect ratios tailored for Shopee listings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Banana Image generate a sunset over mountains"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Overview
MCP Banana Image is a Model Context Protocol (MCP) server that brings AI-powered image generation capabilities to your favorite AI coding assistants. Built with Google's Nano Banana 2 (gemini-3.1-flash-image) for image generation and gemini 3 flash for text enhancement, it offers 16 specialized tools for image generation, editing, analysis, and processing - all through a simple natural language interface.
Highlights
16 Specialized Tools - From simple generation to advanced style transfer
Custom API Endpoint Support - Use with Cliproxyapi or other Gemini API proxies
Intelligent Prompt Enhancement - Automatically optimizes your prompts for better results
Dual Transport - STDIO (default) and HTTP (Streamable HTTP Transport)
Docker Ready - Deploy as HTTP server with Docker
Related MCP server: Nano-Banana MCP Server
Features
Category | Features |
Generation | AI image generation, logos, icons, products, social media, UGC, infographics, character sets |
Editing | Image editing, background removal, image blending, style transfer |
Analysis | AI-powered image analysis with descriptions, alt-text, tags, and OCR |
Processing | Format conversion, resizing, compression |
Quality | 2K/4K resolution, 10 aspect ratios, 4 output formats, smart compression |
Consistency | Character consistency, style transfer, reference image support |
Integration | Google Search grounding, world knowledge, platform-specific optimization |
Requirements
Node.js 20+
Gemini API Key from Google AI Studio or Cliproxyapi
Installation
Claude Code
claude mcp add mcp-banana-image \
--env GEMINI_API_KEY=your_api_key \
--env GEMINI_BASE_URL=https://generativelanguage.googleapis.com \
--env IMAGE_OUTPUT_DIR=/path/to/output \
--env SKIP_PROMPT_ENHANCEMENT=false \
-- npx -y mcp-banana-imageAdd --scope user for global installation.
Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"mcp-banana-image": {
"command": "npx",
"args": ["-y", "mcp-banana-image"],
"env": {
"GEMINI_API_KEY": "your_api_key",
"GEMINI_BASE_URL": "https://generativelanguage.googleapis.com",
"IMAGE_OUTPUT_DIR": "/path/to/output",
"SKIP_PROMPT_ENHANCEMENT": "false"
}
}
}
}Codex
Add to ~/.codex/config.toml:
[mcp_servers.mcp-banana-image]
command = "npx"
args = ["-y", "mcp-banana-image"]
[mcp_servers.mcp-banana-image.env]
GEMINI_API_KEY = "your_api_key"
GEMINI_BASE_URL = "https://generativelanguage.googleapis.com"
IMAGE_OUTPUT_DIR = "/path/to/output"
SKIP_PROMPT_ENHANCEMENT = "false"OpenCode
Add to your opencode.json in your project root or ~/.config/opencode/config.json for global config:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp-banana-image": {
"type": "local",
"command": ["npx", "-y", "mcp-banana-image"],
"enabled": true,
"environment": {
"GEMINI_API_KEY": "your_api_key",
"GEMINI_BASE_URL": "https://generativelanguage.googleapis.com",
"IMAGE_OUTPUT_DIR": "/path/to/output",
"SKIP_PROMPT_ENHANCEMENT": "false"
}
}
}
}With Cliproxy custom endpoint:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp-banana-image": {
"type": "local",
"command": ["npx", "-y", "mcp-banana-image"],
"enabled": true,
"environment": {
"GEMINI_API_KEY": "your_cliproxy_api_key",
"GEMINI_BASE_URL": "https://yourdomain.com",
"IMAGE_OUTPUT_DIR": "/path/to/output"
}
}
}
}To use the tool, add use mcp-banana-image to your prompts or add this to your AGENTS.md:
When you need to generate, edit, or analyze images, use `mcp-banana-image` tools.Custom API Endpoint
MCP Banana Image supports custom Gemini API endpoints, allowing you to use alternative API providers like Cliproxy or your own proxy servers.
Using with Cliproxy
Cliproxy is a Gemini API proxy service that provides enhanced reliability, rate limiting, and additional features.
Configuration Example (Claude Code with Cliproxy)
claude mcp add mcp-banana-image \
--env GEMINI_API_KEY=your_cliproxy_api_key \
--env GEMINI_BASE_URL=https://yourdomain.com \
--env IMAGE_OUTPUT_DIR=/path/to/output \
-- npx -y mcp-banana-imageConfiguration Example (manual json)
{
"mcpServers": {
"mcp-banana-image": {
"command": "npx",
"args": ["-y", "mcp-banana-image"],
"env": {
"GEMINI_API_KEY": "your_cliproxy_api_key",
"GEMINI_BASE_URL": "https://yourdomain.com",
"IMAGE_OUTPUT_DIR": "/path/to/output"
}
}
}
}Security Notes
Production: Only HTTPS endpoints are allowed
Development: HTTP/localhost endpoints are permitted for testing
The endpoint URL is validated before use to prevent SSRF attacks
Tools Reference
MCP Banana Image provides 16 specialized tools organized by category:
Image Generation Tools
Tool | Description | Key Features |
| Generate images from text prompts | Auto prompt enhancement, style presets, aspect ratios |
| Advanced generation with full control | All parameters exposed, reference images, character consistency |
| Generate professional logos | Business name/tagline, 8 styles, transparent backgrounds, color branding |
| Generate icons, avatars, stickers | 6 styles (flat, outlined, 3D), multiple sizes (16-512px) |
| E-commerce product photography | 5 style presets, platform compliance (Amazon, Shopee, Tokopedia), 6 categories |
| Platform-optimized social content | 9 platforms, auto aspect ratios, text-safe zones |
| Authentic user-generated content | 7 scenarios, 10 settings, smartphone aesthetic |
| AI-powered infographics | 4 styles, 4 layouts, brand colors, icon hints |
| Consistent character series | Poses, expressions, 5 art styles, sprite sheet output |
Image Editing Tools
Tool | Description | Key Features |
| Edit images with natural language | Add/remove elements, change backgrounds, enhance |
| Remove image backgrounds | Transparent PNG output, AI-powered segmentation |
| Blend multiple images | 4 modes (seamless, collage, double-exposure, overlay), 2-4 images |
| Apply artistic styles | Single/multiple references, style strength control, element preservation |
Image Processing Tools
Tool | Description | Key Features |
| Format conversion | PNG, JPEG, WebP, AVIF, compression presets |
| Resize images | Exact dimensions, 5 fit modes, aspect preservation |
Analysis Tools
Tool | Description | Key Features |
| AI-powered image analysis | Descriptions, alt-text, tags, OCR, moderation |
Usage Examples
Basic Image Generation
"Generate a mountain landscape at sunset"Logo Generation
generate_logo businessName='TechStart' tagline='Innovation Made Simple' style='modern'Product Photography
generate_product productDescription='handmade leather wallet' style='premium' platform='amazon'Social Media Content
generate_social_media content='summer sale announcement' platform='instagram-post'User-Generated Content
generate_ugc description='person enjoying morning coffee' scenario='lifestyle' setting='home'Character Set Generation
generate_character_set characterDescription='friendly robot mascot' poses=['front', 'waving'] style='cartoon'Style Transfer
style_transfer referenceStyleImage='./van-gogh.jpg' contentDescription='mountain landscape' styleStrength=0.8Image Analysis
analyze_image imagePath='/path/to/photo.jpg' analysisType='description'Background Removal
remove_background imagePath='/path/to/product.jpg'Image Blending
blend_images imagePaths=['./bg.jpg', './subject.png'] instruction='Place subject on background' blendMode='seamless'Infographic Generation
generate_infographic content='5 steps to improve productivity: 1. Set goals...' style='corporate' layout='vertical'Image Resizing
resize_image inputPath='./photo.jpg' width=800 height=600 fit='cover'Environment Variables
Core Configuration
Variable | Required | Default | Description |
| Yes | - | Google AI or Cliproxy API key |
| No | Google default | Custom API endpoint (e.g., Cliproxy) |
| No |
| Output directory for generated images |
| No |
| Disable automatic prompt optimization |
HTTP Transport Configuration
Variable | Required | Default | Description |
| No |
| Transport mode: |
| Yes (http) | - | API key for HTTP authentication |
| No |
| HTTP server port |
| No |
| HTTP server bind address |
| No |
| CORS allowed origins |
| No |
| HTTP request timeout in ms |
Output Formats & Compression
Supported Formats
Format | Description | Transparency | Best For |
| Lossless | Yes | Graphics, logos, icons |
| Lossy | No | Photos, large images |
| Modern | Yes | Web optimization |
| Best compression | Yes | Modern browsers |
Compression Presets
Preset | Description | Use Case |
| No quality loss | Archival, source files |
| Minimal loss | Professional work |
| Good quality/size ratio | General use |
| Smallest file size | Web optimization |
Aspect Ratios
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9Docker Deployment
Build and Run
docker build -t mcp-banana-image .
docker-compose updocker-compose.yml
services:
mcp-banana-image:
build: .
ports:
- "3000:3000"
volumes:
- ./output:/app/output
environment:
- GEMINI_API_KEY=${GEMINI_API_KEY}
- GEMINI_BASE_URL=${GEMINI_BASE_URL}
- MCP_API_KEY=${MCP_API_KEY}
- MCP_TRANSPORT=httpHealth Check
curl http://localhost:3000/healthResponse:
{
"status": "ok",
"timestamp": "2024-01-01T00:00:00.000Z",
"sessions": 0
}Architecture
flowchart TB
subgraph Client
A[AI Assistant]
end
subgraph MCP Server
B[Transport Layer]
C[MCP Handler]
D[Tool Registry]
E[16 Specialized Tools]
F[Image Processor]
G[File Manager]
end
subgraph "AI Providers"
H[Gemini API]
I[Cliproxy API]
end
A -->|STDIO/HTTP| B
B --> C
C --> D
D --> E
E -->|API Calls| H
E -->|API Calls| I
E --> F
F -->|Save| G
G --> J[(Output)]Troubleshooting
API key not found
Verify
GEMINI_API_KEYis set correctlyFor Cliproxy: ensure you're using the correct Cliproxy API key
Check key permissions at Google AI Studio
Custom endpoint connection failed
Verify
GEMINI_BASE_URLis correctly formatted (include full URL with protocol)Ensure the endpoint is accessible from your network
For production: only HTTPS endpoints are allowed
Image not saved
Ensure
IMAGE_OUTPUT_DIRis an absolute pathCheck directory write permissions
Verify disk space availability
Generation timeout
High resolution images (4K) take longer
Character sets with many poses/expressions take longer
Consider increasing
MCP_HTTP_TIMEOUTfor HTTP modeCheck network connectivity to API endpoint
Prompt blocked by safety filters
Rephrase your prompt to avoid potentially sensitive content
The AI may reject prompts that could generate inappropriate imagery
Character consistency issues
Provide detailed character descriptions
Use reference images when available
Enable
maintainCharacterConsistencyoption
Development
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Run with coverage
npm run test:coverage
# Lint and format
npm run check:allLicense
MIT
Contributing
We welcome contributions! Please read our Contributing Guide for guidelines on how to submit changes.
Available Tools
15 toolsanalyze_imageA
Analyze images using AI vision to generate descriptions, alt-text, tags, or detailed semantic analysis.
Use this when:
Generating accessible alt-text for images
Creating image descriptions for content management
Auto-tagging images for organization and search
Getting detailed semantic analysis of image content
Extracting text from images (OCR)
NOT for:
Generating new images (use generate_image instead)
Editing or modifying images (use edit_image instead)
Removing backgrounds (use remove_background instead)
Example: "analyze_image imagePath='/path/to/photo.jpg' analysisType='description'"
Inputs: model (required), timeout (required), imagePath (required), skipCache (required), +7 more.
blend_imagesA
Blend multiple images together using AI-powered composition with various blend modes (seamless, collage, double-exposure, overlay).
Use this when:
Combining 2-4 images into a single composition
Creating seamless blends or artistic collages
Making double-exposure effects
Overlaying images with natural transitions
NOT for:
Editing a single image (use edit_image instead)
Generating images from scratch (use generate_image instead)
Simple format conversion (use convert_image instead)
Removing backgrounds only (use remove_background instead)
Example: "blend_images imagePaths=['./bg.jpg', './subject.png'] instruction='Place subject on background' blendMode='seamless'"
Inputs: opacity (required), quality (required), blendMode (required), imagePaths (required), +5 more.
convert_imageA
Convert images between formats without AI processing.
Use this when:
Converting image format (PNG to WebP, JPEG to PNG, etc.)
Optimizing file size with compression settings
Batch format standardization
NOT for:
AI-powered image generation (use generate_image instead)
Content modification with AI (use edit_image instead)
Example: "Convert photo.png to WebP format with 80% quality"
Inputs: inputPath (required), outputFormat (required), stripMetadata (required), quality, +2 more.
edit_imageA
Edit existing images using natural language instructions.
Use this when:
Modifying an existing image
Adding or removing elements from a photo
Changing backgrounds or styles
Enhancing or retouching images
NOT for:
Creating new images from scratch (use generate_image instead)
Format conversion without AI changes (use convert_image instead)
Example: "Remove the background from this product photo"
Inputs: editPrompt (required), preserveStyle (required), fileName, inputImage, +3 more.
generate_character_setA
Generate consistent character images across multiple poses and expressions for character series, mascots, or visual narratives.
Use this when:
Creating character turnarounds (front, side, back views)
Generating expression sheets for the same character
Building consistent mascots or characters across multiple images
Creating sprite sheets for games or animations
NOT for:
Single character image without multiple poses (use generate_image instead)
Editing existing character images (use edit_image instead)
Style transfer between images (use style_transfer instead)
Chain with: If user requests specific pixel dimensions for character images, chain with resize_image after generation.
Example: "generate_character_set characterDescription='friendly robot mascot with blue eyes' poses=['front', 'waving', 'thinking'] style='cartoon'"
Inputs: size (required), style (required), quality (required), outputMode (required), +8 more.
generate_iconA
Generate icons, avatars, and stickers - small visual assets optimized for clarity at small sizes.
Use this when:
Creating app or website icons
Generating user avatars or profile pictures
Creating stickers for messaging apps
Need small, recognizable visual assets
NOT for:
Logos with text or business branding (use generate_logo instead)
Large detailed images (use generate_image instead)
Editing existing icons (use edit_image instead)
Chain with: If user requests specific pixel dimensions for icons (e.g., 512x512, 192x192), chain with resize_image after generation.
Example: "generate_icon description='shopping cart' purpose='icon' style='outlined'"
Inputs: size (required), style (required), purpose (required), description (required), +3 more.
generate_imageA
Generate images from simple text prompts with automatic prompt enhancement for professional results.
Use this when:
Any image generation from text prompts
Need specific pixel dimensions (use targetWidth/targetHeight)
Professional use with precise control over all parameters
Quick generation with sensible defaults
NOT for:
Editing existing images (use edit_image instead)
Format conversion only (use convert_image instead)
Resize existing image without regeneration (use resize_image instead)
Example: "Create a hero image for a coffee shop website"
Inputs: prompt (required), aspectRatio (required), outputFormat (required), stripMetadata (required), +19 more.
generate_infographicA
Generate AI-powered infographic images from content descriptions with customizable styles, layouts, and branding.
Use this when:
Creating visual summaries of data, processes, or concepts
Generating infographics for presentations or social media
Visualizing comparisons, timelines, or step-by-step guides
Creating branded infographics with specific colors and fonts
NOT for:
Simple image generation without data/content (use generate_image instead)
Editing existing infographics (use edit_image instead)
Logo or icon creation (use generate_logo instead)
Product photography (use generate_product instead)
Chain with: If user requests specific pixel dimensions, chain with resize_image after generation.
Example: "generate_infographic content='5 steps to improve productivity: 1. Set goals 2. Prioritize tasks 3. Eliminate distractions 4. Take breaks 5. Review progress' style='corporate' layout='vertical'"
Inputs: style (required), layout (required), content (required), quality (required), +6 more.
generate_logoA
Generate professional logos with text support and multiple style options for branding.
Use this when:
Creating a logo for a business or brand
Need text-integrated logo design
Want specific brand colors in the logo
Need icon-only logo (no text)
NOT for:
Simple icons without branding context (use generate_image instead)
General images not for branding (use generate_image instead)
Editing existing logos (use edit_image instead)
Chain with: If user requests specific pixel dimensions for the logo, chain with resize_image after generation.
Example: "generate_logo businessName='TechStart' tagline='Innovation Made Simple' style='modern'"
Inputs: style (required), iconOnly (required), aspectRatio (required), businessName (required), +7 more.
generate_productA
Generate professional e-commerce product photography that drives purchases with automatic style optimization.
Use this when:
Creating product photos for online stores
Need marketplace-compliant images (Amazon, Shopee, Tokopedia)
Want consistent catalog photography
Need category-optimized shots (food, fashion, electronics, jewelry, furniture)
NOT for:
Artistic or creative images (use generate_image instead)
Logos or branding assets (use generate_logo instead)
Icons or small visual assets (use generate_icon instead)
Editing existing product photos (use edit_image instead)
Chain with: If user requests specific pixel dimensions for marketplace requirements, chain with resize_image after generation.
Example: "generate_product productDescription='handmade leather wallet' style='premium'"
Inputs: lighting (required), platform (required), background (required), aspectRatio (required), +6 more.
generate_social_mediaA
Generate platform-optimized social media content with correct dimensions and engagement-focused styling.
Use this when:
Creating content for Instagram, TikTok, YouTube, Twitter, LinkedIn, Facebook, Pinterest
Need platform-specific aspect ratios automatically applied
Want scroll-stopping, engagement-optimized visuals
Need text-safe zones for overlay design
NOT for:
E-commerce product photography (use generate_product instead)
Logos or branding assets (use generate_logo instead)
General artistic images (use generate_image instead)
Editing existing social media images (use edit_image instead)
Chain with: If user requests specific pixel dimensions beyond platform defaults, chain with resize_image after generation.
Example: "generate_social_media content='summer sale announcement' platform='instagram-post'"
Inputs: content (required), platform (required), outputFormat (required), style, +3 more.
generate_ugcA
Generate authentic user-generated content style images that look natural, relatable, and not AI-generated.
Use this when:
Creating UGC-style content for marketing campaigns
Need authentic, smartphone-quality aesthetic
Want relatable, casual content that connects with audiences
Creating unboxing, lifestyle, review, or testimonial-style visuals
Need diverse, realistic scenarios (home, cafe, gym, outdoor, etc.)
NOT for:
Polished product photography (use generate_product instead)
Professional social media graphics (use generate_social_media instead)
Logos or branding assets (use generate_logo instead)
Editing existing UGC images (use edit_image instead)
Chain with: If user requests specific pixel dimensions, chain with resize_image after generation.
Example: "generate_ugc description='person enjoying morning coffee' scenario='lifestyle' setting='home'"
Inputs: description (required), outputFormat (required), mood, setting, +5 more.
remove_backgroundA
Remove backgrounds from images to create transparent PNGs for product shots, portraits, and design assets.
Use this when:
Creating transparent product images for e-commerce
Removing backgrounds from portraits or headshots
Preparing images for compositing or design work
Converting product photos to transparent PNGs
NOT for:
Adding new backgrounds to images (use edit_image instead)
General image editing (use edit_image instead)
Format conversion without background removal (use convert_image instead)
Example: "remove_background imagePath='/path/to/product.jpg'"
Inputs: imagePath (required), outputFilename.
resize_imageA
Resize images to specific dimensions without AI processing.
Use this when:
Scaling images to specific width/height
Creating thumbnails or previews
Fitting images within size constraints
Batch resizing for web optimization
NOT for:
AI-powered image generation (use generate_image instead)
Content modification with AI (use edit_image instead)
Format conversion only (use convert_image instead)
Example: "resize_image inputPath='./photo.jpg' width=800 height=600 fit='cover'"
Inputs: inputPath (required), stripMetadata (required), withoutReduction (required), withoutEnlargement (required), +8 more.
style_transferA
Apply artistic style from a reference image to new or existing content while preserving the content structure.
Use this when:
Applying artistic styles to new image generations
Transforming existing images with a reference style
Creating consistent visual aesthetics across multiple images
Blending multiple style references together
Analyzing style characteristics before generation
NOT for:
Character consistency across poses (use generate_character_set instead)
Simple image editing (use edit_image instead)
Generating images from scratch without style reference (use generate_image instead)
Chain with: If user requests specific pixel dimensions for styled images, chain with resize_image after generation.
Example: "style_transfer referenceStyleImage='./van-gogh.jpg' contentDescription='mountain landscape at sunset' styleStrength=0.8"
Inputs: size (required), quality (required), aspectRatio (required), outputFormat (required), +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Every tool carries explicit 'Use this when / NOT for / use X instead' guidance, so the eight generate_* variants are clearly separated by domain (logo, icon, product, social, UGC, infographic, character set). The only residual overlap is conceptual: generate_product vs generate_ugc vs generate_social_media can all produce marketing imagery, and style_transfer vs blend_images both combine references, though descriptions steer correctly.
Nearly all names follow a snake_case verb_noun pattern (generate_image, edit_image, convert_image, resize_image, remove_background, analyze_image, blend_images). The single deviation is 'style_transfer', which inverts to noun_verb, a minor inconsistency in an otherwise predictable scheme.
Fifteen tools sit at the top of the well-scoped range for an image media server. Each has a distinct modality or operation, and the specialized generators justify their separation through differing parameters (platform, poses, brand text, layout) rather than being duplicates.
The surface covers the full lifecycle: generation (general + specialized), editing, style transfer, blending, background removal, analysis/OCR, format conversion, and resizing, with documented chaining to resize_image. Minor gaps remain: no crop/rotate/upscale, no text or watermark overlay, and no metadata/inspection tool for existing files.
Maintenance
Related MCP Connectors
MCP server for Qwen Image 3 AI image generation
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
MCP server for Flux AI image generation
Generate AI images and videos from any compatible MCP client.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI image generation, editing, and analysis using Google's Gemini 3.0 models. It supports high-resolution outputs up to 4K, style transfers, and multi-image mixing through specialized tools.3MIT
- AlicenseAqualityDmaintenanceAn MCP server that provides AI image generation and editing capabilities using Google's Gemini 2.5 Flash Image API. It allows users to create new images from text, modify existing files, and perform iterative edits through natural language prompts.61,740 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides image generation using Google's Nano Banana Gemini models, with additional tools for background removal, upscaling, and format conversion via deterministic post-processing.1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Google's Nano Banana image generation models (Gemini). Generate and edit images via natural language.27 npm1MIT