Image Edit MCP Server

AI-powered image editing and generation server using the Model Context Protocol (MCP). Provides tools for intelligent image manipulation, cleanup, and generation using Google's Gemini AI models.

Features

• Image Understanding: Ask questions about images using Gemini 2.5 Pro vision

• Image Generation: Create photorealistic images from text using Imagen 4.0

• Product Image Cleanup: Remove watermarks while preserving backgrounds

• White Background Mode: E-commerce ready product images

• Smart Crop: Center crop to 1:1 square format

• Intelligent Expand: Fill borders with AI-matched backgrounds

• AI Quality Reviews: Automatic quality assessment for generated/edited images

Related MCP server: Gemini MCP Image Generation Server

Tools

1. understand_image

Ask questions about image content using Gemini 2.5 Pro vision.

Parameters:

• image_source (required): Local file path or URL

• question (optional): Your question about the image

Example:

{
  "image_source": "/path/to/image.jpg",
  "question": "What is the main product in this image?"
}

2. generate_image

Generate photorealistic product images from text descriptions using Imagen AI.

Parameters:

• description (required): Detailed image description (max 480 tokens)

• aspect_ratio (optional): 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 1:1)

Example:

{
  "description": "Red ceramic coffee mug, white background, studio lighting, macro lens, sharp focus, professional product photography, 4K",
  "aspect_ratio": "1:1"
}

3. clean_product_image

Remove watermarks and overlays while preserving original background.

Parameters:

• input_path (required): Local file path or URL

• aspect_ratio (optional): Output aspect ratio (default: 1:1)

• additional_instructions (optional): Extra instructions for AI

4. clean_product_image_white_bg

Remove watermarks and replace background with pure white + studio lighting.

Parameters:

• input_path (required): Local file path or URL

• aspect_ratio (optional): Output aspect ratio (default: 1:1)

• additional_instructions (optional): Extra instructions for AI

5. crop_image_to_square

Fast center crop to 1:1 square (1024x1024). No AI processing.

Parameters:

• input_path (required): Local file path or URL

6. expand_image_to_square

Intelligently fill borders to create 1:1 square while preserving original content.

Parameters:

• input_path (required): Local file path or URL

Installation

Prerequisites

• Node.js 18+

• pnpm (recommended) or npm

• Google Gemini API key

Setup

1. Clone or download this repository:

cd ~/projects
git clone <repository-url> image-edit-mcp
cd image-edit-mcp

2. Install dependencies:

pnpm install

3. Create .env file:

cp .env.example .env

4. Add your Gemini API key to .env:

GEMINI_API_KEY=your_api_key_here

# Optional: Use custom Gemini endpoint (e.g., proxy)
# GEMINI_BASE_URL=https://api2.aigcbest.top

Get your API key from: https://aistudio.google.com/app/apikey

Note: The generate_image tool always uses the official Google API as imagen models are not supported by proxy endpoints. Other tools will use GEMINI_BASE_URL if configured.

5. Build the project:

pnpm build

Configuration

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "image-edit": {
      "command": "node",
      "args": ["/Users/shun/projects/image-edit-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

With custom Gemini endpoint (optional):

{
  "mcpServers": {
    "image-edit": {
      "command": "node",
      "args": ["/Users/shun/projects/image-edit-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "GEMINI_BASE_URL": "https://api2.aigcbest.top"
      }
    }
  }
}

Note: generate_image always uses official Google API (imagen models not supported by proxies).

Other MCP Clients

The server communicates via stdio and can be used with any MCP-compatible client. Configure according to your client's documentation.

Output

All processed images are saved to your system's temporary directory with unique filenames:

• macOS/Linux: /tmp/image-edit-mcp/

• Windows: C:\Users\{user}\AppData\Local\Temp\image-edit-mcp\

Output format: High-quality WebP (lossless, quality 100)

API Keys

Gemini API Key

• Required for all image operations

• Free tier: 15 requests per minute, 1500 requests per day

• Get your key: https://aistudio.google.com/app/apikey

Note on Imagen

The generate_image tool uses a hardcoded official Google API key for compatibility. For production use, you should obtain your own Imagen API access.

Development

Build

pnpm build

Watch mode

pnpm dev

Project Structure

image-edit-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── config.ts         # Environment configuration
│   ├── types.ts          # TypeScript type definitions
│   └── tools/
│       └── images.ts     # Image editing tools
├── prompts/              # AI prompts for image operations
├── dist/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"GEMINI_API_KEY is required" error

Make sure your .env file contains a valid Gemini API key, or configure it in your MCP client settings.

Build errors

Try clearing the build cache and reinstalling:

rm -rf node_modules dist
pnpm install
pnpm build

Image generation fails

• Check your API key is valid

• Verify you haven't exceeded rate limits

• Ensure your prompt is under 480 tokens

License

MIT

Credits

Built with:

• Model Context Protocol SDK

• Google Generative AI

• Sharp for image processing