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 Banana 3 Pro, 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

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