Image Gen MCP

A Model Context Protocol (MCP) server that provides AI-powered image generation using Google's Gemini API.

Features

• Image Generation: Generate images from text prompts using Gemini 2.5 Flash Image model
• Reference Images: Support for up to 3 reference images for character consistency, style matching, and object incorporation
• Prompting Resources: Built-in comprehensive prompting guide with examples and templates
• MCP-Compliant: Standard MCP server with stdio transport
• Lightweight: Docker image for easy deployment

Prerequisites

• Go 1.24+ (for local development)
• Docker (for containerized deployment)
• Google Gemini API key

Getting a Gemini API Key

1. Go to Google AI Studio
2. Create a new API key
3. Save it for use in configuration

Installation

Using Docker (Recommended)

Pull from Docker Hub:

docker pull vitaliipsl/image-gen-mcp:latest

Or build locally:

docker build -t image-gen-mcp .

From Source

go build -o bin/image-gen-mcp ./cmd/server

Configuration

The server requires the following environment variables:

Variable	Required	Description
GEMINI_API_KEY	Yes	Your Google Gemini API key
OUTPUT_DIR	No	Directory to save generated images (default: ./generated_images)

You can also create a .env file in the project root:

GEMINI_API_KEY=your_api_key_here
OUTPUT_DIR=/path/to/output

Usage

With Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using Docker

{
  "mcpServers": {
    "image-gen": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GEMINI_API_KEY=your_api_key_here",
        "-v", "/path/to/output:/output",
        "vitaliipsl/image-gen-mcp:latest"
      ]
    }
  }
}

Using Binary

{
  "mcpServers": {
    "image-gen": {
      "command": "/path/to/image-gen-mcp",
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

With Claude Code

Add via CLI:

claude mcp add image-gen /path/to/image-gen-mcp \
  -e GEMINI_API_KEY=your_api_key_here \
  -e OUTPUT_DIR=/path/to/output

Or add to your Claude Code MCP settings:

{
  "mcpServers": {
    "image-gen": {
      "command": "/path/to/image-gen-mcp",
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

Available Tools

generate_image

Generate an image based on a text prompt. Optionally accepts reference images for character consistency, style matching, or incorporating specific objects/people into the generated image.

Parameters:

Parameter	Type	Required	Description
prompt	string	Yes	The text prompt describing the image to generate
aspect_ratio	string	No	Aspect ratio in x:y format (e.g., 16:9, 1:1, 4:3)
reference_images	array[string]	No	Array of file paths to reference images (up to 3 recommended). Use for character consistency, style matching, or incorporating specific objects/people.

Output:

Generated images are saved to the configured OUTPUT_DIR and the tool returns the file path(s). This approach is used instead of returning inline base64 data because MCP clients like Claude have response size limits (~1MB), and high-resolution images from Gemini can exceed this limit.

Examples:

Basic generation:

Generate an image of a sunset over mountains with aspect ratio 16:9

With reference images for character consistency:

Generate an image of this character in a cyberpunk city at night, use reference_images: ["/path/to/character.jpg"]

Style matching:

Generate a landscape in the style of these reference images, use reference_images: ["/path/to/style1.jpg", "/path/to/style2.jpg"]

Available Resources

The server provides comprehensive prompting guides and templates as MCP resources:

Resource URI	Description
prompt://guide/prompting	Complete prompting guide covering core elements, aspect ratios, advanced techniques, photography terms, text rendering, character consistency, and style-specific guidance
prompt://guide/examples	Curated collection of 25+ example prompts demonstrating best practices across all categories
prompt://templates/list	Library of 15 ready-to-use prompt templates across photography, illustration, marketing, educational, and professional categories

What's Included

Prompting Guide:

• Core elements (subject, composition, action, location, style)
• Aspect ratio reference (1:1, 16:9, 9:16, etc.)
• Advanced photography terms and techniques
• Text rendering in images
• Character consistency
• Style-specific guidance

Template Categories:

• Photography: Photorealistic portraits, landscapes, product photography
• Illustration: Character design, stylized art, children's book illustrations
• Marketing: Social media posts, product mockups, event posters
• Educational: Infographics, technical illustrations
• Professional: Architectural visualization, food photography
• Artistic Styles: Anime/manga, oil painting