Gemini Imggen

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

Python uv License: MIT

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