npm package: @lunar30612/mcp-image-tools
Description: MCP server for image manipulation and AI image generation using Google Gemini. Resize images to custom aspect ratios and generate images with customizable prompts.
Author: C29
Latest version: 0.1.0

# @c29/mcp-image-tools

An MCP (Model Context Protocol) server that provides image manipulation and AI image generation tools using Google Gemini.

[![npm version](https://badge.fury.io/js/@c29%2Fmcp-image-tools.svg)](https://www.npmjs.com/package/@c29/mcp-image-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

This MCP server exposes two powerful tools:

### 🖼️ resize_image
Resize and crop images to specific aspect ratios with optional watermark support.

- Smart cropping to maintain aspect ratio
- High-quality image processing with Sharp
- Customizable watermark (size: 3% of image height, opacity: 42%)
- Support for various aspect ratios (9:16, 16:9, 1:1, 4:3, etc.)

### 🎨 generate_images
Generate AI images using Google Gemini with customizable prompts.

- Powered by Gemini 2.5 Flash Image Preview model
- Customizable keywords and artistic styles
- Negative prompt support to avoid unwanted elements
- Automatic watermarking
- Built-in retry logic for failed generations
- Batch generation support

## Installation

```bash
npm install -g @c29/mcp-image-tools
```

## Configuration

### For Cline/Claude Desktop

Add to your MCP settings configuration file:

**Cline**: `~/.vscode/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

**Claude Desktop**: 
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "image-tools": {
      "command": "npx",
      "args": ["-y", "@c29/mcp-image-tools"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}
```

### Getting a Gemini API Key

1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the key and add it to your MCP configuration

## Usage

Once configured, you can use the tools through your MCP client (Cline, Claude Desktop, etc.):

### Resize Images

```
Resize the image at /path/to/image.png to 16:9 aspect ratio
```

```
Resize all images in the img/ folder to 1:1 aspect ratio with watermark "MyBrand"
```

### Generate Images

```
Generate 3 photorealistic images of a mountain landscape
```

```
Generate images with keyword "sunset beach", style "oil painting", and negative prompt "people, buildings"
```

```
Generate 5 anime-style images of cats with custom watermark "CatArt2025"
```

## API Reference

### resize_image

**Parameters:**
- `inputPath` (required): Path to the input image file
- `outputPath` (optional): Path for the output image file (defaults to overwriting input)
- `aspectRatio` (optional): Desired aspect ratio in format "width:height" (default: "9:16")
- `watermarkText` (optional): Text to add as watermark (default: "C29")

**Example:**
```json
{
  "inputPath": "/path/to/image.png",
  "outputPath": "/path/to/output.png",
  "aspectRatio": "16:9",
  "watermarkText": "MyBrand"
}
```

### generate_images

**Parameters:**
- `keyword` (required): Main keyword/subject for the image
- `style` (required): Artistic style (e.g., "photorealistic", "oil painting", "anime")
- `numImages` (optional): Number of images to generate (default: 1)
- `aspectRatio` (optional): Aspect ratio for generation prompt (default: "9:16")
- `outputDir` (optional): Directory to save generated images (default: "./generated_images")
- `watermarkText` (optional): Text to add as watermark (default: "C29")
- `negativePrompt` (optional): Things to avoid in the generated image
- `maxRetries` (optional): Maximum retries per image (default: 5)

**Example:**
```json
{
  "keyword": "futuristic city",
  "style": "cyberpunk art",
  "numImages": 3,
  "aspectRatio": "16:9",
  "watermarkText": "FutureTech",
  "negativePrompt": "blurry, low quality, text"
}
```

## Technical Details

- **Image Processing**: Uses Sharp library for high-performance image manipulation
- **AI Model**: Gemini 2.5 Flash Image Preview for generation
- **Watermark**: SVG overlay with 3% font size and 42% opacity
- **Automatic Retries**: Built-in retry mechanism for failed image generations
- **Directory Creation**: Automatically creates output directories if they don't exist

## Troubleshooting

### API Key Issues
- Verify your Gemini API key is correct
- Ensure the key has proper permissions at [Google AI Studio](https://aistudio.google.com/app/apikey)
- Restart your MCP client after updating the configuration

### Image Processing Errors
- Ensure input paths are correct and files exist
- Check that input files are valid image formats (PNG, JPG, etc.)
- Verify you have write permissions for output directories

### Generation Failures
- The server will automatically retry failed generations up to `maxRetries` times
- Check your Gemini API quota if multiple generations fail
- Review server logs for specific error messages

## Development

To modify or contribute to this server:

```bash
git clone https://github.com/Lunar-feedmob/llm-video-batch.git
cd llm-video-batch/mcp-servers/image-tools-server
npm install
npm run build
```

## License

MIT License - see [LICENSE](LICENSE) file for details

## Author

C29

## Repository

[https://github.com/Lunar-feedmob/llm-video-batch](https://github.com/Lunar-feedmob/llm-video-batch)

## Keywords

MCP, Model Context Protocol, Image Processing, AI Image Generation, Gemini, Sharp, Resize, Watermark, Aspect Ratio