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.10+-blue.svg" alt="Python 3.10+"></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

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

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>

# 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>

{
  "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	Dependency missing	Run uv sync to install all dependencies

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.10+
• 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.