Skip to main content
Glama

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

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-image

Add --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-image

Configuration 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_image

Generate images from text prompts

Auto prompt enhancement, style presets, aspect ratios

generate_image_pro

Advanced generation with full control

All parameters exposed, reference images, character consistency

generate_logo

Generate professional logos

Business name/tagline, 8 styles, transparent backgrounds, color branding

generate_icon

Generate icons, avatars, stickers

6 styles (flat, outlined, 3D), multiple sizes (16-512px)

generate_product

E-commerce product photography

5 style presets, platform compliance (Amazon, Shopee, Tokopedia), 6 categories

generate_social_media

Platform-optimized social content

9 platforms, auto aspect ratios, text-safe zones

generate_ugc

Authentic user-generated content

7 scenarios, 10 settings, smartphone aesthetic

generate_infographic

AI-powered infographics

4 styles, 4 layouts, brand colors, icon hints

generate_character_set

Consistent character series

Poses, expressions, 5 art styles, sprite sheet output

Image Editing Tools

Tool

Description

Key Features

edit_image

Edit images with natural language

Add/remove elements, change backgrounds, enhance

remove_background

Remove image backgrounds

Transparent PNG output, AI-powered segmentation

blend_images

Blend multiple images

4 modes (seamless, collage, double-exposure, overlay), 2-4 images

style_transfer

Apply artistic styles

Single/multiple references, style strength control, element preservation

Image Processing Tools

Tool

Description

Key Features

convert_image

Format conversion

PNG, JPEG, WebP, AVIF, compression presets

resize_image

Resize images

Exact dimensions, 5 fit modes, aspect preservation

Analysis Tools

Tool

Description

Key Features

analyze_image

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.8

Image 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

GEMINI_API_KEY

Yes

-

Google AI or Cliproxy API key

GEMINI_BASE_URL

No

Google default

Custom API endpoint (e.g., Cliproxy)

IMAGE_OUTPUT_DIR

No

./output

Output directory for generated images

SKIP_PROMPT_ENHANCEMENT

No

false

Disable automatic prompt optimization

HTTP Transport Configuration

Variable

Required

Default

Description

MCP_TRANSPORT

No

stdio

Transport mode: stdio or http

MCP_API_KEY

Yes (http)

-

API key for HTTP authentication

MCP_HTTP_PORT

No

3000

HTTP server port

MCP_HTTP_HOST

No

0.0.0.0

HTTP server bind address

MCP_CORS_ORIGIN

No

*

CORS allowed origins

MCP_HTTP_TIMEOUT

No

300000

HTTP request timeout in ms

Output Formats & Compression

Supported Formats

Format

Description

Transparency

Best For

png

Lossless

Yes

Graphics, logos, icons

jpeg

Lossy

No

Photos, large images

webp

Modern

Yes

Web optimization

avif

Best compression

Yes

Modern browsers

Compression Presets

Preset

Description

Use Case

lossless

No quality loss

Archival, source files

high

Minimal loss

Professional work

balanced

Good quality/size ratio

General use

maximum

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:9

Docker Deployment

Build and Run

docker build -t mcp-banana-image .
docker-compose up

docker-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=http

Health Check

curl http://localhost:3000/health

Response:

{
  "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_KEY is set correctly

  • For Cliproxy: ensure you're using the correct Cliproxy API key

  • Check key permissions at Google AI Studio

Custom endpoint connection failed

  • Verify GEMINI_BASE_URL is 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_DIR is an absolute path

  • Check 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_TIMEOUT for HTTP mode

  • Check 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 maintainCharacterConsistency option

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:all

License

MIT

Contributing

We welcome contributions! Please read our Contributing Guide for guidelines on how to submit changes.


Available Tools

15 tools
analyze_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_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

    A3.9/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers