banana-image-mcp 1.0.0

A production-ready MCP server for AI-powered image generation using Gemini 3 Pro Image and Gemini 2.5 Flash Image with intelligent model selection

Banana Image MCP

Let Claude Generate Stunning Images for You

中文文档 | Report Issues

---

What is Banana Image MCP?

Banana Image MCP is an MCP (Model Context Protocol) server that enables Claude and other AI assistants to generate high-quality images using Google's latest Gemini image models.

Simply describe what you want, and Claude will create it - from quick concept sketches to stunning 4K professional artwork.

Key Features

Feature	Description
4K Ultra HD	Generate images up to 3840px with Pro model
Dual Model Support	Flash (fast, 2-3s) + Pro (4K quality, 5-8s)
Smart Model Selection	Automatically picks the best model based on your prompt
Google Search Grounding	Pro model uses real-world knowledge for accuracy
Flexible Aspect Ratios	1:1, 16:9, 9:16, 4:3, 3:2, 21:9 and more
Image Editing	Edit existing images with natural language
Advanced Reasoning	Configurable thinking levels for complex compositions

Quick Start

1. Get a Gemini API Key

Get your free API key from Google AI Studio

2. Install & Configure

For Claude Desktop, add to your config file:

{
  "mcpServers": {
    "banana-image": {
      "command": "uvx",
      "args": ["banana-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Config file locations

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Other MCP clients (Cursor, VS Code, Cline, etc.)

The configuration is similar for other MCP-compatible clients:

{
  "mcpServers": {
    "banana-image": {
      "command": "uvx",
      "args": ["banana-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Updating to the latest version

When using uvx, packages are cached locally. To get the latest version after an update:

# Clear the cache for this package
uv cache clean banana-image-mcp

# Then restart your MCP client (Claude Desktop, etc.)

Or specify a version explicitly:

{
  "mcpServers": {
    "banana-image": {
      "command": "uvx",
      "args": ["banana-image-mcp==1.0.0"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Start Creating

Just ask Claude to generate images:

"Generate a cute cat wearing a space suit"

"Create a professional product photo of a coffee cup, 4K quality"

"Make a 16:9 YouTube thumbnail about cooking"

"Edit this image: make the sky more dramatic"

Models Comparison

Model	Speed	Max Resolution	Best For
Gemini 2.5 Flash	2-3s	1024px	Quick drafts, iterations, prototypes
Gemini 3 Pro	5-8s	4K (3840px)	Final assets, marketing, professional work

Model Selection

The server defaults to Pro model for best quality. You can also control it:

Say this...	Model Used
"quick sketch", "draft", "prototype"	Flash
"4K", "professional", "high quality"	Pro
(default)	Pro

Tool Parameters

Parameter	Type	Default	Description
prompt	string	required	Image description
model_tier	string	"pro"	"flash", "pro", or "auto"
resolution	string	"4k"	"1k", "2k", "4k", "high"
aspect_ratio	string	-	"1:1", "16:9", "9:16", "4:3", "21:9", etc.
thinking_level	string	"high"	"low" or "high" (Pro only)
enable_grounding	bool	true	Enable Google Search grounding (Pro only)
n	int	1	Number of images (1-4)
negative_prompt	string	-	What to avoid in the image

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	-	Your Gemini API key
IMAGE_OUTPUT_DIR	No	~/banana-images	Where to save generated images

Example Outputs

Here are some examples of what you can create:

• Product Photography: Professional product shots with studio lighting
• Concept Art: Fantasy landscapes, character designs, sci-fi scenes
• Marketing Materials: Social media graphics, banners, thumbnails
• Technical Diagrams: Flowcharts, architecture diagrams with text
• Photo-realistic Images: Portraits, nature, urban photography

Development

# Clone the repository
git clone https://github.com/zengwenliang416/banana-image-mcp.git
cd banana-image-mcp

# Install dependencies
uv sync

# Run in development mode
fastmcp dev banana_image_mcp.server:create_app

# Run tests
pytest

# Lint and format
ruff check .
ruff format .

Changelog

v1.0.0

• First stable release
• 4K resolution output support (up to 3840px)
• Dual model support: Flash (fast) + Pro (4K quality)
• Intelligent model selection based on prompt
• Google Search grounding for Pro model
• Flexible aspect ratios (1:1, 16:9, 9:16, 4:3, 21:9, etc.)
• Image editing with natural language
• GitHub Actions CI/CD workflow

v0.1.2

• Added 4K resolution output support
• Default to Pro model and 4K resolution
• Fixed image_size parameter passing to Gemini API

v0.1.1

• Updated package metadata and author info

v0.1.0

• Initial release with dual model support

Links

• PyPI Package
• GitHub Repository
• Report Issues

License

MIT License - see LICENSE for details.

---

Made with by Wenliang Zeng

If you find this useful, please consider giving it a star!