Lazy Media Mcp

lazy-media-mcp

[](https://www.npmjs.com/package/lazy-media-mcp) [](https://github.com/leaf76/lazy-media-mcp/blob/main/LICENSE) [](https://www.npmjs.com/package/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
• lazymobile_mcp — Android/iOS mobile automation MCP
• session-collab-mcp — multi-session collaboration MCP

License

[MIT](./LICENSE) © leaf76

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: leaf76
• Source: leaf76/lazy-media-mcp
• License: MIT
• Homepage: https://www.npmjs.com/package/lazy-media-mcp

Install and usage instructions live in the source repository linked above.