MCP 服务器

MCP Banana Image

AI-powered image generation MCP server with 16 specialized tools for generating, editing, analyzing, and processing images using Google's Nano Banana 2 model. Supports custom API endpoints and integrates with AI coding assistants via natural language.

README

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

AI-Powered Image Generation MCP Server using Google Nano Banana 2 with custom endpoint

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

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.

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