image-edit-mcp

ShunL12324/image-edit-mcp

3.2

If you are the rightful owner of image-edit-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

AI-powered image editing and generation server using the Model Context Protocol (MCP) with Google's Gemini AI models.

Tools
6
Resources
0
Prompts
0

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

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
  1. Install dependencies:
pnpm install
  1. Create .env file:
cp .env.example .env
  1. 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.

  1. 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

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: