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:

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:

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:

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:

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:

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