mrn-gemini-imagen-mcp

MCP (Model Context Protocol) server for generating and editing images using Google Gemini API.

Quick Start

1. Get your API key from Google AI Studio
2. Add to Claude Desktop config:

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "npx",
      "args": ["-y", "mrn-gemini-imagen-mcp"],
      "env": { "GEMINI_API_KEY": "your-api-key-here" }
    }
  }
}

3. Restart Claude Desktop and start generating images!

Features

• Text-to-Image Generation: Generate images from text descriptions
• Image Editing: Modify existing images based on text prompts
• Multi-turn Iteration: Refine images through conversational editing sessions
• Configurable Aspect Ratios: Support for 10 different aspect ratios
• Flexible Model Selection: Use any Gemini image model via configuration

Prerequisites

• Node.js >= 18.0.0
• Google Gemini API Key (get one from Google AI Studio)

Installation

Option 1: Using npx (Recommended)

No installation needed! Just configure Claude Desktop or Claude Code to use it directly via npx.

Option 2: Global Install

npm install -g mrn-gemini-imagen-mcp

Option 3: From Source

git clone https://github.com/mernorthzide/mrn-gemini-imagen-mcp.git
cd mrn-gemini-imagen-mcp
npm install
npm run build

Configuration

Set the following environment variables:

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	-	Your Google Gemini API key
GEMINI_MODEL	No	gemini-3-pro-image-preview	Gemini model to use
GEMINI_OUTPUT_DIR	No	./generated_images	Output directory for images

Supported Models

• gemini-3-pro-image-preview (default, latest)
• gemini-2.5-flash-image (stable, faster)

Supported Aspect Ratios

1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

Note: Aspect ratio is optional. If not specified, Gemini will automatically select the best aspect ratio based on your prompt.

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Using npx (Recommended)

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "npx",
      "args": ["-y", "mrn-gemini-imagen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using Global Install

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "mrn-gemini-imagen-mcp",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage with Claude Code

Add to your Claude Code settings file (~/.claude.json):

{
  "mcpServers": {
    "gemini-imagen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mrn-gemini-imagen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tip: Set GEMINI_MODEL to gemini-2.5-flash-image for faster generation.

Tools

1. generate_image

Generate an image from a text description.

Parameters:

Parameter	Type	Required	Description
prompt	string	Yes	Description of the image to generate
aspectRatio	string	No	Aspect ratio (auto-selected by Gemini if not provided)
outputPath	string	No	Custom output file path

Example:

{
  "prompt": "A serene Japanese garden with a koi pond and cherry blossoms",
  "aspectRatio": "16:9"
}

Response:

{
  "success": true,
  "filePath": "/path/to/a_serene_japanese_garden_1705123456789.png",
  "message": "Image generated successfully"
}

2. edit_image

Edit an existing image based on a text prompt.

Parameters:

Parameter	Type	Required	Description
imagePath	string	Yes	Path to the image to edit
prompt	string	Yes	Instructions for editing
aspectRatio	string	No	Aspect ratio for output
outputPath	string	No	Custom output file path

Example:

{
  "imagePath": "/path/to/original.png",
  "prompt": "Change the sky to a beautiful sunset with orange and pink colors"
}

3. iterate_image

Iteratively refine an image through multi-turn conversation.

Parameters:

Parameter	Type	Required	Description
prompt	string	Yes	Instructions for this iteration
sessionId	string	No	Session ID from previous iteration
imagePath	string	Conditional	Required when starting new session
aspectRatio	string	No	Aspect ratio for output

Starting a new session:

{
  "imagePath": "/path/to/original.png",
  "prompt": "Add a rainbow in the background"
}

Response:

{
  "success": true,
  "filePath": "/path/to/add_a_rainbow_1705123456789.png",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Image iteration completed. Use the same sessionId to continue editing."
}

Continuing the session:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "prompt": "Make the rainbow more vibrant and add some birds"
}

Error Handling

All tools return structured error responses when something goes wrong:

{
  "success": false,
  "error": {
    "code": "SAFETY_BLOCKED",
    "message": "Content was blocked by safety filters",
    "reason": "HARM_CATEGORY_DANGEROUS_CONTENT"
  }
}

Error Codes:

Code	Description
SAFETY_BLOCKED	Content blocked by safety filters
API_ERROR	Error from Gemini API
INVALID_INPUT	Invalid input parameters
FILE_ERROR	File read/write error

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server directly
npm start

File Structure

mrn-gemini-imagen-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript types and constants
│   ├── services/
│   │   └── geminiClient.ts   # Gemini API wrapper
│   ├── tools/
│   │   ├── generateImage.ts  # Text-to-image tool
│   │   ├── editImage.ts      # Image editing tool
│   │   └── iterateImage.ts   # Multi-turn iteration tool
│   └── utils/
│       ├── fileManager.ts    # File operations
│       └── sessionManager.ts # Session management
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Acknowledgments

• Google Gemini API
• Model Context Protocol