<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](https://github.com/router-for-me/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](https://aistudio.google.com/apikey) or [Cliproxyapi](https://github.com/router-for-me/CLIProxyAPI)

## Installation

### Claude Code

```bash
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`:

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

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

```json
{
  "$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:

```json
{
  "$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`:

```markdown
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](https://github.com/router-for-me/CLIProxyAPI)** or your own proxy servers.

### Using with Cliproxy

[Cliproxy](https://github.com/router-for-me/CLIProxyAPI) is a Gemini API proxy service that provides enhanced reliability, rate limiting, and additional features.

### Configuration Example (Claude Code with Cliproxy)

```bash
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)

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

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

### docker-compose.yml

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

```bash
curl http://localhost:3000/health
```

**Response:**

```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "sessions": 0
}
```

## Architecture

```mermaid
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](https://aistudio.google.com/apikey)

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

```bash
# 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](./CONTRIBUTING.md)
for guidelines on how to submit changes.

---

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