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:

1. Shrinks images to a sensible size/quality
2. Turns videos into frame packs agents can actually open
3. 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)

Related

• lazy-desktop-mcp — desktop computer-use MCP
• lazy_mobile_mcp — Android/iOS mobile automation MCP
• session-collab-mcp — multi-session collaboration MCP

License

MIT © leaf76