MCP 服务器

lazy-media-mcp

Local MCP server that compresses images and videos, extracts video frames, and prepares media for AI vision agents by returning file paths instead of inline base64.

README

lazy-media-mcp

Local Model Context Protocol (MCP) server that compresses images/videos and prepares media for AI vision agents.

Designed for coding agents (Claude Code, Codex, Grok, and other MCP clients): returns file paths only (no inline base64), so large screenshots and demos stay within tool limits.

Keywords: MCP server, image compression, video compression, ffmpeg, sharp, AI vision prep, frame extraction, Claude, Codex.

Why this exists

Large screenshots and long demos burn context and often fail tool limits. This server:

Shrinks images to a sensible size/quality
Turns videos into frame packs agents can actually open
Uses JPEG by default for widest agent compatibility

WebP / WebM — do they help AI “read better”?

Format	Role	Default here?
JPEG	Best universal image input for local agents	Yes
PNG	Sharper for OCR / UI text / alpha	`ocr_text` profile
WebP	Smaller files when the host supports it	Opt-in only
MP4	Storage/sharing re-encode	Video compress default
WebM	Optional container	Opt-in via `video_compress`

Format does not improve model understanding by itself. Resolution, blur, and compression artifacts matter more. Over-aggressive WebP/JPEG hurts OCR.

Local agents usually do not natively watch WebM/MP4. Prefer prepare_for_ai / video_extract_frames → JPEG paths.

Requirements

Node.js ≥ 20
ffmpeg + ffprobe on PATH (video tools)

# macOS
brew install ffmpeg

Install / run

From npm

npx -y lazy-media-mcp
# or
npm install -g lazy-media-mcp

From source

git clone https://github.com/leaf76/lazy-media-mcp.git
cd lazy-media-mcp
npm install
npm run build
npm test
node dist/cli.js   # stdio MCP

MCP client config (example)

{
  "mcpServers": {
    "lazy-media": {
      "command": "node",
      "args": ["/absolute/path/to/lazy-media-mcp/dist/cli.js"],
      "env": {
        "MEDIA_ALLOWED_ROOTS": "/Users/you,/Users/you/WorkSpace",
        "MEDIA_WORKDIR": "/Users/you/.cache/lazy-media-mcp/jobs"
      }
    }
  }
}

Tools

Tool	Purpose
`media_inspect`	Metadata only
`image_compress`	Resize/compress image → workdir path
`video_compress`	Re-encode video (default MP4)
`video_extract_frames`	Extract frames for vision
`prepare_for_ai`	One-shot profile pipeline (recommended)
`media_cleanup`	Delete a job directory by `job_id`

`prepare_for_ai` profiles

Profile	Behavior
`ai_vision` (default)	Image → JPEG ≤1536 edge; video → up to 10 JPEG frames
`ocr_text`	Prefer PNG / higher quality
`inline_small`	Smaller edges, fewer frames
`archive`	Higher quality + optional compressed MP4

Environment

Variable	Default
`MEDIA_ALLOWED_ROOTS`	`$HOME`, cwd, workdir
`MEDIA_WORKDIR`	`~/.cache/lazy-media-mcp/jobs`
`MEDIA_MAX_INPUT_BYTES`	500MB
`MEDIA_MAX_OUTPUT_BYTES`	200MB
`MEDIA_MAX_FRAMES`	24
`MEDIA_PROCESS_TIMEOUT_MS`	120000
`FFMPEG_BIN` / `FFPROBE_BIN`	`ffmpeg` / `ffprobe`
`LOG_LEVEL`	`info`

Security

Path allowlist (realpath checks)
Input/output size caps
Process timeout
ffmpeg/ffprobe invoked with argv arrays only (no shell interpolation)
Outputs go to workdir; originals are not overwritten
Cleanup only deletes direct children of workdir by job_id

Typical agent flow

1. prepare_for_ai({ path: "/path/to/demo.mp4", profile: "ai_vision" })
2. Read returned outputs[].path frame files in the next vision step
3. media_cleanup({ job_id }) when done (optional)