本地图像处理工具包

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:

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.

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

Custom Output Directory

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

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.