# Media Toolkit MCP Server

<p align="center">
  <!-- Banner placeholder -->
  <strong>Local Image Processing Toolkit for AI Assistants</strong>
</p>

<p align="center">
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP"></a>
  <img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version 1.0.0">
</p>

<p align="center">
  Background removal, stock media search, resize, format conversion, and collage creation.<br>
  All free and local — no cloud APIs needed (except optional Pexels search).<br>
  Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
</p>

<p align="center">
  <a href="README_CN.md">中文文档</a>
</p>

## Features

- **5 tools** — `remove_background`, `search_stock_media`, `resize_image`, `convert_format`, `create_collage`
- **Free & local** — no paid cloud APIs required for image processing
- **AI background removal** — powered by rembg (U2Net), runs entirely on your machine
- **Stock photo search** — search millions of free photos via Pexels (free API key)
- **Smart resize** — fit, fill, or center crop modes
- **Format conversion** — PNG, JPG, WebP, SVG→PNG
- **Grid collage** — arrange multiple images into customizable grids
- Auto-save output images to disk with timestamps

## Architecture

```
User Prompt → AI Assistant (Claude / Cursor) → MCP Server → Local Processing (Pillow / rembg)
                                                   ↓
                                             Save to disk + Display
```

### How It Works

All image processing happens locally using Python libraries:

| Tool | Library | Cloud API? | Notes |
|---|---|---|---|
| `remove_background` | rembg (U2Net) | No | Model downloads on first use (~170MB) |
| `search_stock_media` | httpx | Pexels API (free) | Requires free API key |
| `resize_image` | Pillow | No | Fit, fill, crop modes |
| `convert_format` | Pillow | No | PNG/JPG/WebP/SVG→PNG |
| `create_collage` | Pillow | No | Grid layout with spacing |

## Quick Start

**1. Clone & install**

```bash
git clone https://github.com/kevinten-ai/mcp-media-toolkit.git
cd mcp-media-toolkit
uv sync
```

Background removal is optional because its ML dependencies are much larger than the core server:

```bash
uv sync --extra background-removal
```

**2. (Optional) Get a free Pexels API key** — visit https://www.pexels.com/api/ → sign up → copy your key

**3. Configure MCP**

<details>
<summary><b>Claude Code (CLI)</b></summary>

```bash
# Without Pexels (all local tools work without any API key)
claude mcp add --transport stdio mcp-media-toolkit \
  -- uv --directory /path/to/mcp-media-toolkit run media-toolkit

# With Pexels stock photo search
claude mcp add --transport stdio mcp-media-toolkit \
  --env PEXELS_API_KEY=your_pexels_key \
  -- uv --directory /path/to/mcp-media-toolkit run media-toolkit
```
</details>

<details>
<summary><b>Claude Desktop / Cursor (JSON config)</b></summary>

```json
{
  "mcpServers": {
    "mcp-media-toolkit": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-media-toolkit", "run", "media-toolkit"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_key"
      }
    }
  }
}
```
</details>

**4. Use it** — just ask your AI assistant:

```
"Remove the background from /path/to/photo.png"
"Search for stock photos of mountain landscapes"
"Resize this image to 1920x1080 using fill mode"
"Convert image.png to WebP format"
"Create a 3-column collage from these 6 images"
```

Output images are automatically saved to the `output/` directory.

## Tools

### remove_background — AI Background Removal

Remove image backgrounds using the rembg library (U2Net model). Runs entirely locally.

```
remove_background(image_path="/path/to/photo.png")
remove_background(image_path="photo.jpg", output_path="/custom/output/result.png")
```

| Parameter | Required | Description |
|---|---|---|
| `image_path` | Yes | Path to the input image |
| `output_path` | No | Custom output path (auto-generated if omitted) |

> **Note:** The first call downloads the U2Net model (~170MB). Subsequent calls are fast.

### search_stock_media — Free Stock Photo Search

Search millions of free stock photos via the Pexels API.

```
search_stock_media(query="sunset beach")
search_stock_media(query="office workspace", count=10, orientation="landscape")
```

| Parameter | Required | Description |
|---|---|---|
| `query` | Yes | Search terms (e.g. "sunset beach") |
| `count` | No | Number of results (default: 5, max: 80) |
| `orientation` | No | Filter: `landscape`, `portrait`, or `square` |

Returns image URLs (original, large, medium) with photographer credits.

### resize_image — Resize & Crop

Resize images with three modes:

```
resize_image(image_path="photo.png", width=1920, height=1080)
resize_image(image_path="photo.png", width=800, height=800, mode="fill")
resize_image(image_path="photo.png", width=500, height=500, mode="crop")
```

| Parameter | Required | Description |
|---|---|---|
| `image_path` | Yes | Path to the input image |
| `width` | Yes | Target width in pixels |
| `height` | Yes | Target height in pixels |
| `mode` | No | `fit` (default, contain), `fill` (cover + crop), `crop` (center crop) |
| `output_path` | No | Custom output path |

**Modes explained:**
- **fit** — Resize to fit within the bounds, preserving aspect ratio. Result may be smaller than target.
- **fill** — Resize to cover the bounds, then center crop. Result is exactly the target size.
- **crop** — Center crop the original image to the target size (no resize).

### convert_format — Format Conversion

Convert between PNG, JPG, WebP. Also supports SVG→PNG (requires cairosvg).

```
convert_format(image_path="photo.png", output_format="webp")
convert_format(image_path="icon.svg", output_format="png")
convert_format(image_path="photo.webp", output_format="jpg")
```

| Parameter | Required | Description |
|---|---|---|
| `image_path` | Yes | Path to the input image |
| `output_format` | Yes | Target format: `png`, `jpg`, `webp` |
| `output_path` | No | Custom output path |

> **Note:** Converting RGBA images to JPEG automatically composites onto a white background.

### create_collage — Grid Collage

Arrange multiple images into a grid layout.

```
create_collage(image_paths=["a.png", "b.png", "c.png", "d.png"])
create_collage(image_paths=["a.png", "b.png", "c.png"], columns=3, spacing=20)
```

| Parameter | Required | Description |
|---|---|---|
| `image_paths` | Yes | List of image file paths |
| `columns` | No | Grid columns (default: 2) |
| `spacing` | No | Pixel spacing between images (default: 10) |
| `output_path` | No | Custom output path |

Images are automatically resized to fit uniform cells within the grid.

### Safety limits

- Resize width and height must be between 1 and 8192 pixels.
- A collage accepts 1–50 images, 1–20 columns, and 0–512 pixels of spacing.
- Pexels searches return 1–80 results.
- Collage canvases are limited to 40 million pixels.
- Inline MCP image previews are limited to 5 MiB; larger results remain available at the returned file path.
- A custom `output_path` must use the target format's extension, must differ from every input path, and must not already exist. Tools never overwrite source images or existing outputs.

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `PEXELS_API_KEY` | No* | — | Pexels API key for stock photo search. *Only required for `search_stock_media` tool. Free at [pexels.com/api](https://www.pexels.com/api/) |
| `IMAGE_OUTPUT_DIR` | No | `./output` | Directory to save output images |

## Custom Output Directory

```bash
--env IMAGE_OUTPUT_DIR=/absolute/path/to/your/images
```

Images are saved with microsecond timestamps: `rembg_20260331_143022_123456.png`, `resize_20260331_143055_123456.jpg`, etc.

## Troubleshooting

### Common Errors

| Error | Root Cause | Solution |
|---|---|---|
| `PEXELS_API_KEY is required` | Missing API key for stock search | Get a free key at [pexels.com/api](https://www.pexels.com/api/) and set `PEXELS_API_KEY` |
| `Image not found: /path/to/file` | File doesn't exist at given path | Check the file path is correct and the file exists |
| `rembg is not installed` | Optional dependency missing | Run `uv sync --extra background-removal` |

### Background Removal

| Issue | Solution |
|---|---|
| First call is very slow (~30s) | Normal — rembg downloads U2Net model (~170MB) on first use. Subsequent calls are fast. |
| Poor removal quality | Try images with clear subject/background contrast. rembg works best with distinct foregrounds. |
| Out of memory | Large images (>4000px) use significant RAM. Resize first with `resize_image`. |

### Format Conversion

| Issue | Solution |
|---|---|
| SVG conversion fails | Install cairosvg: `pip install cairosvg` (requires system Cairo library) |
| JPEG output has black areas | Transparent regions in source image. The tool auto-composites onto white — check input has correct alpha. |
| WebP not supported | Ensure Pillow is built with WebP support (default in most installations) |

### Pexels API

| Issue | Solution |
|---|---|
| 429 Too Many Requests | Free tier allows 200 requests/hour and 20,000/month. Wait or upgrade. |
| No results | Try broader search terms. Pexels search works best with English keywords. |

## Prerequisites

- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** — install with `curl -LsSf https://astral.sh/uv/install.sh | sh`

## Local Development

```bash
git clone https://github.com/kevinten-ai/mcp-media-toolkit.git
cd mcp-media-toolkit

# Install dependencies
uv sync

# Run the server directly
uv run media-toolkit
```

### Debug with MCP Inspector

```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-media-toolkit run media-toolkit
```

## Related Projects

- [mcp-image-gen](https://github.com/kevinten-ai/mcp-image-gen) — AI image generation via Google Gemini and Imagen
- [mcp-video-gen](https://github.com/kevinten-ai/mcp-video-gen) — Multi-provider AI video generation MCP server
- [mcp-3d-gen](https://github.com/kevinten-ai/mcp-3d-gen) — AI 3D model generation MCP server

## License

MIT — see [LICENSE](LICENSE) for details.