# 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:**
```json
{
  "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:**
```json
{
  "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:
```bash
cd ~/projects
git clone <repository-url> image-edit-mcp
cd image-edit-mcp
```

2. Install dependencies:
```bash
pnpm install
```

3. Create `.env` file:
```bash
cp .env.example .env
```

4. Add your Gemini API key to `.env`:
```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:
```bash
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`

```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):**
```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",
        "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
```bash
pnpm build
```

### Watch mode
```bash
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:
```bash
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](https://github.com/anthropics/mcp)
- [Google Generative AI](https://ai.google.dev/)
- [Sharp](https://sharp.pixelplumbing.com/) for image processing