Gemini Image Generation MCP Server

A token-optimized MCP server that enables Gemini image generation in MCP clients by returning file paths instead of base64 data.

Why This Exists

Existing Gemini image generation MCP servers fail in Claude Code with MCP tool response exceeded token limit errors. They return base64-encoded image data (~2.4M tokens per image), exceeding Claude Code's 25,000 token limit.

This implementation solves the problem by saving images to disk and returning only file paths (~20 tokens) — a 120,000× reduction in token usage.

Implementation	Response	Tokens	Result
Existing servers	Base64 data	2.4M	❌ Error
This server	File path	~20	✅ Works

Features

• Token-optimized: Returns file paths only (~20 tokens vs 2.4M)
• Two generation modes: Text-to-image and image-to-image transformation
• Claude Code compatible: Works within 25,000 token limit
• ISO 8601 UTC timestamps: Globally sortable filenames (YYYYMMDDTHHMMSSZ.png)
• Lightweight: Minimal dependencies
• Fast: uv-powered startup
• Simple: No build step required

Requirements

• Python 3.10+
• uv - Modern Python package manager (10-100× faster than pip)
• Gemini API key from Google AI Studio

Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew
brew install uv

# Verify installation
uv --version

Quick Start

# 1. Clone and navigate
git clone https://github.com/couhie/mcp-gemini-imggen.git
cd mcp-gemini-imggen

# 2. Configure settings
cp .env.example .env
# Edit .env and set:
#   GEMINI_API_KEY - Your API key from Google AI Studio
#   OUTPUT_DIR - Directory for generated images (e.g., ~/Pictures/ai)
#                Directory will be created automatically if it doesn't exist

# 3. Add to Claude Code
claude mcp add -s user gemini-imggen uv -- --directory $(pwd) run mcp-gemini-imggen

Configuration

Claude Code CLI (Recommended)

claude mcp add -s user gemini-imggen uv -- --directory /absolute/path/to/mcp-gemini-imggen run mcp-gemini-imggen

Manual Setup

Add to ~/.claude.json:

{
  "mcpServers": {
    "gemini-imggen": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-gemini-imggen",
        "run",
        "mcp-gemini-imggen"
      ],
      "env": {}
    }
  }
}

Note: Use absolute paths, not ~ (e.g., /Users/yourname/dev/mcp-gemini-imggen)

Usage

Once configured, use the MCP tools in Claude Code:

Text-to-Image Generation

Generate a flat design style cute cat illustration

Image-to-Image Transformation

Transform /Users/name/Pictures/ai/20251015T120000Z.png: make the background blue

Note: You must provide the file path to an existing image. Common use cases:

• Modify previously generated images
• Transform images already saved on your system
• Chain transformations: generate → transform → transform again

The server will:

1. Generate/transform the image using Gemini 2.5 Flash
2. Save it to $OUTPUT_DIR/YYYYMMDDTHHMMSSZ.png (ISO 8601 UTC format)
3. Return only the file path (~20 tokens)

Claude Code will automatically display the generated image.

Technical Details

Token Optimization

Base64-encoded responses cause token explosion:

1. 1536×1536 PNG ≈ 1.4MB → Base64 ≈ 1.9MB (33% overhead)
2. Token conversion: 1.9MB ÷ 4 chars/token ≈ 475,000 tokens
3. Multiple images (4×): ~1,900,000 tokens
4. JSON wrapper: +500,000 tokens
5. Total: ~2,400,000 tokens (exceeds 25,000 limit)

Solution: Return file path instead of data

# ❌ Existing: 2.4M tokens
{"type": "image", "data": "iVBORw0KGgo...", "mimeType": "image/png"}

# ✅ This server: ~20 tokens
[{"type": "text", "text": "/Users/name/Pictures/ai/20251015T120000Z.png"}]

Troubleshooting

"uv: command not found"

Install uv first:

curl -LsSf https://astral.sh/uv/install.sh | sh

"GEMINI_API_KEY environment variable is required"

Get your API key from Google AI Studio and add to .env

"OUTPUT_DIR environment variable is required"

Set your desired output directory in .env (e.g., OUTPUT_DIR=~/Pictures/ai). The directory will be created automatically if it doesn't exist.

Images not generating

• Verify API key is valid at Google AI Studio
• Check API quota limits
• Verify OUTPUT_DIR path is valid (parent directories must be writable)

Contributing

Contributions are welcome! Please submit a Pull Request.

License

MIT License - see LICENSE for details.

Links

• MCP Documentation
• Google Gemini API
• uv Package Manager