gemini-image-mcp 1.0.0

MCP server for AI-powered image generation using Google Gemini models

gemini-image-mcp

MCP server for AI-powered image generation using Google Gemini models.

Also known as "Nano Banana" - the friendly name for this image generation server.

Features

• Dual Model Support: Flash (2-3s, 1024px) and Pro (4K quality)
• Smart Model Selection: Auto-selects based on prompt keywords
• Aspect Ratio Control: 1:1, 16:9, 9:16, 21:9, 4:3, 3:4, 2:1
• Google Search Grounding: Factually accurate images (Pro only)
• File Management: Upload, list, and delete files via Gemini Files API
• Reproducible Generation: Seed support for consistent results

Installation

Via uvx (Recommended)

No installation needed - runs directly:

uvx gemini-image-mcp

Via pip

pip install gemini-image-mcp

Via pipx

pipx install gemini-image-mcp

Configuration

Environment Variable

Get your free API key from Google AI Studio.

export GEMINI_API_KEY="your-api-key-here"

Claude Code Integration

Add to your .mcp.json:

{
  "mcpServers": {
    "nano-banana": {
      "command": "uvx",
      "args": ["gemini-image-mcp"]
    }
  }
}

Or configure in ~/.claude/settings.json:

{
  "env": {
    "GEMINI_API_KEY": "your-api-key-here"
  }
}

Tools

generate_image

Generate images with automatic model selection.

mcp__nano-banana__generate_image

Parameters:

• prompt (required): Image description
• model_tier: "flash", "pro", or "auto" (default: auto)
• aspect_ratio: "1:1", "16:9", "9:16", etc. (default: 1:1)
• thinking_level: "LOW" or "HIGH" (Pro only)
• use_grounding: Enable Google Search grounding (Pro only)
• safety_level: "STRICT", "MODERATE", "PERMISSIVE", "OFF"
• seed: Integer for reproducible results
• output_path: File path to save image

list_files

List uploaded files.

mcp__nano-banana__list_files

upload_file

Upload a file for use as reference.

mcp__nano-banana__upload_file

delete_file

Delete an uploaded file.

mcp__nano-banana__delete_file

Model Selection

Pro model auto-selects for prompts containing:

• professional, 4k, high quality, detailed, photorealistic
• ultra, premium, studio, commercial, product photo

Flash model auto-selects for prompts containing:

• quick, fast, sketch, draft, concept, rough
• preview, test, iterate, simple, basic

Development

# Clone and setup
git clone https://github.com/channel47/nano-banana-mcp.git
cd nano-banana-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
ruff format src/ tests/
ruff check src/ tests/

License

MIT