Gemini Image MCP Server

A Model Context Protocol (MCP) server for image generation and editing using Google Gemini AI. Supports optional context images to guide results and now includes a dedicated edit workflow. Optimized for creating eye‑catching social media images with square (1:1) format by default.

Features

• ✨ Image generation with Google Gemini AI

• 🎨 Multiple aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4)

• 📱 Optimized for social media with 1:1 format by default

• 🎯 Custom style support

• 🧩 Context images to guide generation

• ✏️ Dedicated edit tool for modifying existing assets without juggling extra options

• 🏷️ Watermark support - Overlay watermark images on generated results

• 💾 Automatic saving of images to local files

• 📁 Flexible output path configuration

• 🛡️ Customizable safety settings

Installation

1. Clone this repository

2. Install dependencies:

3. Build the project:

Configuration

Environment Variables

You need to configure your Google AI API key:

Getting Google AI API Key

1. Go to Google AI Studio

2. Create a new API key

3. Copy the key and set it as an environment variable

Client Configuration

Command Line Interface

In addition to the MCP server, the project now ships with a CLI for quick terminal-friendly workflows.

1. Build the project once:

   npm run build

2. Make sure GOOGLE_API_KEY is set in your environment.

3. Explore the CLI:

   node dist/cli.js --help # or, after publishing/packing: gemini-image --help

Commands

• gemini-image generate: Create new imagery from a text prompt.

  gemini-image generate --prompt "A banana astronaut on Mars" --output ./images/

• gemini-image edit: Apply instructions to an existing image.

  gemini-image edit --prompt "Add neon lights to the skyline" --input ./images/city.png

Both commands support --help for detailed, friendly option descriptions. CLI option names are intentionally concise (for example --prompt, --context, --input) so they are easier to memorize than the MCP tool identifiers.

Available Tools

generate_image

Creates a brand-new image from a text description, optionally using one or more images as visual context. Use this tool when you want to generate fresh content.

Parameters:

• description (string, required): Detailed description of the desired image.

• images (string[], optional): Array of image paths used as context (absolute or relative). Use this to “edit” or guide style/content.

• aspectRatio (string, optional): Orientation preset (square, landscape, portrait). Default: square.

• style (string, optional): Additional style (e.g., "minimalist", "colorful", "professional", "artistic").

• outputPath (string, optional): Where to save the image. If omitted, saves in current directory.

• watermarkPath (string, optional): Path to watermark image to overlay.

• watermarkPosition (string, optional): One of top-left, top-right, bottom-left, bottom-right. Default: bottom-right.

Usage Examples:

When you request a specific orientation (square, landscape, or portrait), the server automatically appends an invisible helper image (assets/square.png, assets/landscape.png, or assets/portrait.png) so Gemini respects the target dimensions.

edit_image

Modifies an existing image using a focused text instruction. This tool keeps the original framing unless you explicitly ask for structural changes.

Parameters:

• description (string, required): Instructions describing the edits to apply to the provided image.

• image (string, required): Path to the image file you want to edit (absolute or relative).

• outputPath (string, optional): Where to save the edited result. If omitted, the server uses the working directory and an auto-generated filename.

Usage Examples:

Watermark Functionality

The generate_image tool supports adding watermarks to your images:

Features:

• 🏷️ Add image watermarks to any generated output

• 📍 Position in any corner (watermarkPosition)

• 📏 Smart sizing (25% of image width, maintaining aspect ratio)

• 🎯 Consistent spacing (3% padding from edges)

• 🖼️ Supports PNG, JPG, WebP watermark files

• ⚡ Only applied when watermarkPath parameter is provided

Usage:

Watermark Specifications:

• Position: Configurable corner via watermarkPosition

• Size: 25% of image width (maintains watermark aspect ratio)

• Padding: 3% of image width from the selected edges

• Blend mode: Over (watermark appears on top of image)

Save Functionality:

• Default: Images are saved in the directory from where the MCP client is executed

• Automatic naming: Generated based on description, date and time

• Supported formats: PNG, JPG, WebP (depending on what Gemini returns)

• Automatic creation: Creates necessary folders if they don't exist

Development

Available Scripts

• npm run build: Compiles TypeScript to JavaScript

• npm run dev: Development mode with automatic reload

• npm start: Runs the compiled server

• npm run cli: Runs the CLI entry directly (node dist/cli.js)

Project Structure

Troubleshooting

Error: "GOOGLE_API_KEY environment variable is required"

Make sure you have configured the GOOGLE_API_KEY environment variable with your Google AI API key.

Error: "Could not generate image"

• Verify that your API key is valid and has permissions for the gemini-2.5-flash-image-preview model

• Ensure the description doesn't contain content that might be blocked by safety filters

File saving error

• Verify you have write permissions in the specified path

• Make sure the path is valid and accessible

• If specifying a folder, end it with /

Server not responding

• Verify the server is running correctly

• Check logs in stderr for error messages

• Make sure the MCP client is configured correctly

License

MIT

Contributing

Contributions are welcome. Please open an issue before making significant changes.