内容
# 懒媒体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)
**本地模型上下文协议（MCP）服务器**，**压缩图片/视频**，并**为AI视觉代理准备媒体**。
设计用于编码代理（Claude Code、Codex、Grok和其他MCP客户端）：仅返回**文件路径**（不含内联base64），因此大型截图和演示文稿仍在工具限制内。
**关键词：** MCP服务器、图片压缩、视频压缩、ffmpeg、sharp、AI视觉准备、帧提取、Claude、Codex。
## 为什么存在
大型截图和长演示文稿会占用上下文并经常超出工具限制。该服务器：
1. 将图片缩小到合适的大小/质量
2. 将视频转换为**帧包**，代理可以直接打开
3. 默认使用**JPEG**，以获得最广泛的代理兼容性
### WebP / WebM — 它们能帮助AI“更好地阅读”吗？
| 格式 | 角色 | 默认值 |
|--------|------|----------------|
| **JPEG** | 本地代理的最佳通用图片输入 | **是** |
| **PNG** | 更适合OCR/UI文本/alpha | `ocr_text` 配置文件 |
| **WebP** | 当主机支持时，文件更小 | **仅需时启用** |
| **MP4** | 存储/共享重新编码 | 视频压缩默认值 |
| **WebM** | 可选容器 | 通过 `video_compress` 启用 |
**格式本身并不能提高模型理解能力。** 分辨率、模糊和压缩伪影更为重要。过度激进的WebP/JPEG会损害OCR。
本地代理通常**不原生支持WebM/MP4**。请优先使用 `prepare_for_ai` / `video_extract_frames` → JPEG路径。
## 要求
- Node.js ≥ 20
- [ffmpeg](https://ffmpeg.org/) + ffprobe 在 `PATH` 上（视频工具）
```bash
# macOS
brew install ffmpeg
```
## 安装/运行
### 从npm
```bash
npx -y lazy-media-mcp
# 或
npm install -g lazy-media-mcp
```
### 从源码
```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 # 标准输入MCP
```
### MCP客户端配置（示例）
```json
{
"mcpServers": {
"lazy-media": {
"command": "node",
"args": ["/绝对路径/to/lazy-media-mcp/dist/cli.js"],
"env": {
"MEDIA_ALLOWED_ROOTS": "/Users/你,/Users/你/WorkSpace",
"MEDIA_WORKDIR": "/Users/你/.cache/lazy-media-mcp/jobs"
}
}
}
}
```
## 工具
| 工具 | 目的 |
|------|---------|
| `media_inspect` | 仅元数据 |
| `image_compress` | 调整大小/压缩图片 → 工作目录路径 |
| `video_compress` | 重新编码视频（默认MP4） |
| `video_extract_frames` | 为视觉提取帧 |
| `prepare_for_ai` | 一次性配置文件管道（**推荐**） |
| `media_cleanup` | 按 `job_id` 删除作业目录 |
### `prepare_for_ai` 配置文件
| 配置文件 | 行为 |
|---------|----------|
| `ai_vision` （默认） | 图片 → JPEG ≤1536边缘；视频 → 多达10个JPEG帧 |
| `ocr_text` | 优先使用PNG / 更高质量 |
| `inline_small` | 更小的边缘，更少的帧 |
| `archive` | 更高质量 + 可选压缩MP4 |
## 环境
| 变量 | 默认值 |
|----------|---------|
| `MEDIA_ALLOWED_ROOTS` | `$HOME`，cwd，工作目录 |
| `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` |
## 安全
- 路径允许列表（真实路径检查）
- 输入/输出大小上限
- 进程超时
- ffmpeg/ffprobe仅使用argv数组（无shell插值）
- 输出到工作目录；原始文件不被覆盖
- 清理仅按 `job_id` 删除工作目录的直接子项
## 典型代理流程
```text
1. prepare_for_ai({ path: "/path/to/demo.mp4", profile: "ai_vision" })
2. 在下一个视觉步骤中读取返回的outputs[].path帧文件
3. 完成后使用 `media_cleanup({ job_id })` （可选）
```
## 相关
- [lazy-desktop-mcp](https://github.com/leaf76/lazy-desktop-mcp) — 桌面计算机使用MCP
- [lazy_mobile_mcp](https://github.com/leaf76/lazy_mobile_mcp) — Android/iOS移动自动化MCP
- [session-collab-mcp](https://github.com/leaf76/session-collab-mcp) — 多会话协作MCP
## 许可证
[MIT](./LICENSE) © leaf76
