Media Toolkit MCP Server

Local Image Processing Toolkit for AI Assistants

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

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

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:

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>Claude Code (CLI)</summary>

# 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>Claude Desktop / Cursor (JSON config)</summary>

{
  "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.

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 | | IMAGE_OUTPUT_DIR | No | ./output | Directory to save output images |

Custom Output Directory

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

Images are saved with timestamps: rembg_20260331_143022.png, resize_20260331_143055.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 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 — install with curl -LsSf https://astral.sh/uv/install.sh | sh

Local Development

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

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

Related Projects

mcp-image-gen — AI image generation via Google Gemini and Imagen
mcp-video-gen — Multi-provider AI video generation MCP server
mcp-3d-gen — AI 3D model generation MCP server

License

MIT — see LICENSE for details.

Media Toolkit MCP Server