Content
# 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](https://ffmpeg.org/) + ffprobe on `PATH` (video tools)
```bash
# macOS
brew install ffmpeg
```
## Install / run
### From npm
```bash
npx -y lazy-media-mcp
# or
npm install -g lazy-media-mcp
```
### From source
```bash
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)
```json
{
"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
```text
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](https://github.com/leaf76/lazy-desktop-mcp) — desktop computer-use MCP
- [lazy_mobile_mcp](https://github.com/leaf76/lazy_mobile_mcp) — Android/iOS mobile automation MCP
- [session-collab-mcp](https://github.com/leaf76/session-collab-mcp) — multi-session collaboration MCP
## License
[MIT](./LICENSE) © leaf76
