MCP Banana Image

<p align="center"> <img src="assets/mcp-banana-image.webp" alt="MCP Banana Image" width="400"/> </p>

<h1 align="center">MCP Banana Image</h1>

<p align="center"> <strong>AI-Powered Image Generation MCP Server using Google Nano Banana 2 with custom endpoint</strong> </p>

<p align="center"> <a href="https://www.npmjs.com/package/mcp-banana-image"> <img src="https://img.shields.io/npm/v/mcp-banana-image?style=flat-square&color=yellow" alt="npm version"/> </a> <a href="https://www.npmjs.com/package/mcp-banana-image"> <img src="https://img.shields.io/npm/dm/mcp-banana-image?style=flat-square&color=green" alt="npm downloads"/> </a> <a href="https://github.com/trigidigital/mcp-banana-image/blob/main/LICENSE"> <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license"/> </a> <a href="https://nodejs.org/"> <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version"/> </a> <a href="#"> <img src="https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript" alt="TypeScript"/> </a> <a href="#"> <img src="https://img.shields.io/badge/MCP-1.0-purple?style=flat-square" alt="MCP SDK"/> </a> </p>

<p align="center"> <a href="#features">Features</a> • <a href="#installation">Installation</a> • <a href="#usage">Usage</a> • <a href="#tools-reference">Tools</a> • <a href="#custom-api-endpoint">Custom API Endpoint</a> • <a href="#docker-deployment">Docker</a> • <a href="#troubleshooting">Troubleshooting</a> </p>

---

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

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.

---

<p align="center"> Made with ❤️ by <a href="https://trigidigital.com">Trigi Digital</a> </p>