mrn-gemini-imagen-mcp

![npm version](https://www.npmjs.com/package/mrn-gemini-imagen-mcp) ![License: MIT](https://opensource.org/licenses/MIT)

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

Quick Start

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

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

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: ``json { "prompt": "A serene Japanese garden with a koi pond and cherry blossoms", "aspectRatio": "16:9" } ``

Response: ``json { "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: ``json { "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: ``json { "imagePath": "/path/to/original.png", "prompt": "Add a rainbow in the background" } ``

Response: ``json { "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: ``json { "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

mrn-gemini-imagen-mcp