Media Toolkit MCP Server
This server is a local image processing toolkit for MCP-enabled AI assistants, offering:
Background Removal (
remove_background): AI-based (rembg/U2Net) that runs locally, auto-downloading the model on first use—no cloud API needed.Stock Photo Search (
search_stock_media): Query millions of free photos via Pexels API (free key required), filterable by orientation and count, with credits.Image Resizing (
resize_image): Resize/crop usingfit,fill, orcropmodes, dimensions from 1–8192px.Format Conversion (
convert_format): Convert among PNG, JPG, WebP, and rasterize SVG to PNG; auto-handles alpha for JPEG.Collage Creation (
create_collage): Grid collages from 1–50 images, configurable columns (1–20) and spacing (0–512px).
All operations except stock search are local and free. Processed files are auto-saved with timestamps. Works with Claude, Cursor, and other MCP clients.
Allows searching millions of free stock photos via the Pexels API, returning image URLs with photographer credits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Media Toolkit MCP Server Remove the background from ~/Pictures/photo.jpg"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Media Toolkit MCP Server
Features
5 tools —
remove_background,search_stock_media,resize_image,convert_format,create_collageFree & 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
Related MCP server: ImageMcp
Architecture
User Prompt → AI Assistant (Claude / Cursor) → MCP Server → Local Processing (Pillow / rembg)
↓
Save to disk + DisplayHow It Works
All image processing happens locally using Python libraries:
Tool | Library | Cloud API? | Notes |
| rembg (U2Net) | No | Model downloads on first use (~170MB) |
| httpx | Pexels API (free) | Requires free API key |
| Pillow | No | Fit, fill, crop modes |
| Pillow | No | PNG/JPG/WebP/SVG→PNG |
| 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 syncBackground removal is optional because its ML dependencies are much larger than the core server:
uv sync --extra background-removal2. (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")Parameter | Required | Description |
| Yes | Path to the input image |
| 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 |
| Yes | Search terms (e.g. "sunset beach") |
| No | Number of results (default: 5, max: 80) |
| No | Filter: |
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 |
| Yes | Path to the input image |
| Yes | Target width in pixels |
| Yes | Target height in pixels |
| No |
|
| 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 |
| Yes | Path to the input image |
| Yes | Target format: |
| 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 |
| Yes | List of image file paths |
| No | Grid columns (default: 2) |
| No | Pixel spacing between images (default: 10) |
| 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_pathmust 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 |
| No* | — | Pexels API key for stock photo search. *Only required for |
| No |
| Directory to save output images |
Custom Output Directory
--env IMAGE_OUTPUT_DIR=/absolute/path/to/your/imagesImages are saved with microsecond timestamps: rembg_20260331_143022_123456.png, resize_20260331_143055_123456.jpg, etc.
Troubleshooting
Common Errors
Error | Root Cause | Solution |
| Missing API key for stock search | Get a free key at pexels.com/api and set |
| File doesn't exist at given path | Check the file path is correct and the file exists |
| Optional dependency missing | Run |
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 |
Format Conversion
Issue | Solution |
SVG conversion fails | Install cairosvg: |
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-toolkitDebug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-media-toolkit run media-toolkitRelated 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.
Available Tools
5 toolsconvert_formatC
Convert an image between formats: PNG, JPG, WebP, or SVG to PNG. Works locally with Pillow. Note: SVG input is rasterized to PNG via cairosvg if available, otherwise Pillow.
Inputs: image_path (required), output_format (required), output_path.
create_collageB
Arrange multiple images into a grid collage. Images are resized to fit uniformly. Works locally with Pillow.
Inputs: image_paths (required), columns, spacing, output_path.
remove_backgroundA
Remove the background from an image using AI (rembg). Works locally — no cloud API needed. The model (~170MB) is downloaded automatically on first use.
Inputs: image_path (required), output_path.
resize_imageA
Resize or crop an image to specific dimensions. Supports three modes: fit (preserve aspect ratio, fit within bounds), fill (preserve aspect ratio, cover bounds), crop (center crop to exact size). Works locally with Pillow.
Inputs: width (required), height (required), image_path (required), mode, +1 more.
search_stock_mediaA
Search free stock photos via the Pexels API. Returns image URLs with photographer credits. Requires PEXELS_API_KEY env var (free at pexels.com/api).
Inputs: query (required), count, orientation.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: format conversion, collage creation, background removal, resizing, and stock photo search. There is no ambiguity or overlap among them.
All tool names follow the consistent verb_noun pattern (e.g., convert_format, create_collage, remove_background) with underscores, making them predictable and easy to understand.
With 5 tools, the set is well-scoped for a media toolkit. It covers essential image operations without being excessive or too sparse.
The toolkit covers common image tasks like conversion, collage, background removal, resizing, and stock search. However, missing operations like filtering, text overlay, or rotation represent minor gaps that agents may need to work around.
Maintenance
Related MCP Connectors
Image processing over MCP: compress and split images, generate images and QR codes.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
AI-powered image processing via GPU. Remove backgrounds and upscale images (2x/4x) directly from any MCP client. OAuth 2.1 authenticated, returns processed images inline with download links. Free credits on signup at maskr.io.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for generating, editing, and processing images via multiple providers including Kilo, OpenRouter, OpenAI, and Gemini, with local tools for background removal, resizing, and cropping.27 npm3MIT
- FlicenseNot gradedqualityDmaintenanceA full-featured image processing MCP server for AI assistants, exposing ~55 tools across 11 categories for editing, layers, conversion, AI segmentation/cleanup/generation, design analysis, and screenshot-to-code.-
- FlicenseNot gradedqualityDmaintenanceA powerful Model Context Protocol (MCP) server for image processing, designed to empower AI models with advanced image manipulation capabilities.1-
- AlicenseAqualityCmaintenanceA local MCP server that provides image processing tools including resizing, cropping, format conversion, compression, rotation, flipping, thumbnailing, watermarking, effects, placeholder generation, and overlaying.121MIT