Media Toolkit 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:

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

# 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

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

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")

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")

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")

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")

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)

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

Environment Variables

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

Background Removal

Format Conversion

Pexels API

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.