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

Related MCP server: mcp-media-engine

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

prepare_for_ai profiles

Environment

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