Which integrations are available for this server?

Generates and edits images using the Google Gemini API, supporting text-to-image generation, image editing, and multi-turn iterative refinement.

How do I use mrn-gemini-imagen-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mrn-gemini-imagen-mcp generate a serene Japanese garden with koi pond" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mrn-gemini-imagen-mcp

by mernorthzide

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

mrn-gemini-imagen-mcp

npm version License: 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!

Related MCP server: Nano-Banana MCP Server

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

Available Tools

3 tools

edit_imageA

Edit an existing image based on a text prompt using Google Gemini. Useful for modifying specific parts of an image while preserving others.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	Instructions for how to edit the image (e.g., 'Change the sky to sunset colors' or 'Add a cat in the foreground')
`imagePath`	Yes	Path to the image file to edit
`outputPath`	No	Optional custom file path for saving the edited image
`aspectRatio`	No	Optional aspect ratio for the output image. If not provided, Gemini will auto-select. Options: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behaviors. It mentions using Gemini and that it preserves other parts, but does not clarify if edits are destructive, file format support, or whether outputPath is needed to avoid overwriting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first defines purpose, second provides a usage hint. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks details on output behavior (e.g., where the edited image is saved, file format), prerequisites (image must exist), and error handling. For a file-modifying tool, this is insufficient without annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so descriptions already explain parameters. The tool description does not add extra meaning beyond the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool edits an existing image using a text prompt with Google Gemini. It specifies the resource (existing image) and the action (edit), distinguishing it from siblings generate_image and iterate_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear use case: modifying specific parts while preserving others. Implicitly distinguishes from generate_image (creation) and iterate_image (likely iteration), but does not explicitly state when to avoid using it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageB

Generate an image from a text description using Google Gemini. Returns the file path of the generated image.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	A detailed description of the image you want to generate
`outputPath`	No	Optional custom file path for saving the image. If not provided, uses auto-generated filename in output directory.
`aspectRatio`	No	Optional aspect ratio for the generated image. If not provided, Gemini will auto-select based on the prompt. Options: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description must cover behavioral traits. It mentions the model and return value but omits details like potential costs, rate limits, side effects (e.g., storage usage), or any safety/ethical considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence. Every word adds value, and the most important information (action, model, output) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately states the return value (file path). For 3 parameters and a straightforward generation task, this is sufficient, though additional details like supported file formats could further improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what the schema already provides for each parameter. The 'outputPath' and 'aspectRatio' are adequately described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (generate), resource (image), input source (text description), model (Google Gemini), and output (file path). It implicitly distinguishes from siblings 'edit_image' and 'iterate_image' by focusing on generation from description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'edit_image' or 'iterate_image'. No context on prerequisites or scenarios where this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

iterate_imageB

Iteratively refine an image through multi-turn conversation. Start a new session with an image, or continue an existing session to make incremental adjustments.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	Instructions for the current iteration (e.g., 'Make the colors warmer' or 'Add more detail to the background')
`imagePath`	No	Path to the initial image. Required when starting a new session (no sessionId provided).
`sessionId`	No	Session ID from a previous iteration. Omit to start a new session.
`aspectRatio`	No	Optional aspect ratio for the output image. If not provided, Gemini will auto-select. Options: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavioral traits. It does not explain what happens during iteration (e.g., state management, side effects, whether the image is modified in place or returned). Key behaviors like output format and session lifecycle are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the purpose. No redundant information; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 4 parameters and no output schema, the description is insufficient. It lacks details on return values, session behavior, and how iterations affect previous state. Agent would be uncertain about what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the parameter descriptions in the schema. It does not explain how parameters interact or provide examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: iterative image refinement through multi-turn conversation. It distinguishes between starting a new session and continuing an existing one, and the name 'iterate_image' contrasts with siblings 'edit_image' (single edit) and 'generate_image' (creation from scratch).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage context (start new or continue session) but does not explicitly advise when to use this tool versus alternatives like 'edit_image' or 'generate_image'. No guidance on prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.0.0Jul 6, 2026
- First observededit_image
- First observedgenerate_image
- First observediterate_image

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Scored 2026-07-06 15:10 across 3 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: generate creates new images, edit modifies existing ones with a single prompt, and iterate enables multi-turn refinement. The descriptions make the boundaries unambiguous.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (generate_image, edit_image, iterate_image), making them easy to understand and predict.

Tool Count5/5

Three tools is an ideal size for this domain—covering creation, editing, and iterative refinement without redundancy or unnecessary bloat.

Completeness5/5

The tool surface fully covers the core image manipulation workflow: generate from scratch, edit with a prompt, and iteratively refine through conversation. No obvious gaps for the intended purpose.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
MidjourneyOAuth
io.github.AceDataCloud
MCP server for Midjourney AI image generation and editing
Image & Video Processing Multimedia Processing Art & Culture
29
mcp-nanobanana-proOAuth
io.github.AceDataCloud
MCP server for NanoBanana AI image generation and editing
Image & Video Processing Multimedia Processing
27

Related MCP Servers

gemini-image-mcp
App Automation Image & Video Processing Content Management Systems
creating-cat
A
license
B
quality
C
maintenance
An MCP server for image generation using the Gemini API.
Updated a year ago (2025-07-22 08:13 UTC)
1
33
2
MIT
Nano-Banana MCP Server
AI & Machine Learning Image & Video Processing
bongartzdiaz
A
license
A
quality
D
maintenance
An MCP server that provides AI image generation and editing capabilities using Google's Gemini 2.5 Flash Image API. It allows users to create new images from text, modify existing files, and perform iterative edits through natural language prompts.
Updated 5 months ago (2026-03-28 12:32 UTC)
6
269
MIT
Gemini Gen MCP
AI & Machine Learning Audio Processing Image & Video Processing
ServiceStack
A
license
B
quality
C
maintenance
MCP server for generating images and audio using Google's Gemini AI models.
Updated 8 months ago (2026-01-19 13:37 UTC)
2
2
MIT
Nano Banana MCP
Image & Video Processing AI & Machine Learning
charlesdove977
A
license
A
quality
D
maintenance
MCP server for Google Gemini image generation with configurable model support, enabling text-to-image generation, image editing, and iterative refinement.
Updated 5 months ago (2026-03-30 16:16 UTC)
6
40
MIT

mrn-gemini-imagen-mcp

Quick Start

Features

Prerequisites

Installation

Option 1: Using npx (Recommended)

Option 2: Global Install

Option 3: From Source

Configuration

Supported Models

Supported Aspect Ratios

Usage with Claude Desktop

Using npx (Recommended)

Using Global Install

Usage with Claude Code

Tools

1. generate_image

2. edit_image

3. iterate_image

Error Handling

Development

File Structure

License

Acknowledgments

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

1. `generate_image`

2. `edit_image`

3. `iterate_image`