# ffmpeg-mcp

FFmpeg MCP Server — 将常用 FFmpeg 操作封装为 MCP 工具，支持 AI 助手直接调用。

## 功能特性

支持 **17 个实用 FFmpeg 工具**：

| 工具 | 功能 | 典型用途 |
|------|------|----------|
| `probe` | 获取媒体文件详细信息 | 查看视频分辨率、编码、时长、码率 |
| `convert` | 格式转换 | MP4→MKV, AVI→MP4, WAV→MP3 |
| `compress` | 视频压缩 | CRF 控制质量，H.264/H.265 编码 |
| `extract_audio` | 提取音频 | 从视频中提取 MP3/AAC/WAV/FLAC |
| `thumbnail` | 生成缩略图 | 指定时间点截图或均匀截取多张 |
| `trim` | 裁剪/切割 | 按时间范围截取片段（无重编码） |
| `merge` | 合并拼接 | 多个视频合并为一个 |
| `watermark` | 添加水印 | 图片水印或文字水印，支持位置/透明度 |
| `gif` | 转 GIF | 高质量双通道调色板 GIF 生成 |
| `resize` | 调整分辨率 | 缩放视频到指定尺寸 |
| `speed` | 变速 | 0.25x 慢放到 4x 快进 |
| `rotate` | 旋转/翻转 | 90°/180°/270° 旋转，水平/垂直翻转 |
| `add_audio` | 添加音轨 | 替换或混合视频中的音频 |
| `subtitle` | 添加字幕 | 硬编码或软字幕（SRT/ASS/VTT） |
| `volume` | 调整音量 | 音量增减或 EBU R128 标准化 |
| `crop` | 裁剪画面 | 按区域裁剪视频画面 |
| `frames` | 提取帧 | 按帧率导出图片序列 |

## 传输模式

| 模式 | 命令 | 适用场景 |
|------|------|----------|
| **stdio** | `npx ffmpeg-mcp` | Claude Code, Cursor, Windsurf |
| **SSE** | `npx ffmpeg-mcp --transport sse` | Web 客户端（旧版协议） |
| **Streamable HTTP** | `npx ffmpeg-mcp --transport http` | Web 客户端（新版协议） |

## 前置条件

- Node.js >= 18
- FFmpeg 已安装并在 PATH 中（运行 `ffmpeg -version` 验证）

## 安装

```bash
npm install
npm run build
```

## 客户端配置

### Claude Code

```bash
claude mcp add ffmpeg-mcp -- node /path/to/ffmpeg-mcp/dist/index.js
```

或在 `~/.claude/settings.json` 中：

```json
{
  "mcpServers": {
    "ffmpeg": {
      "command": "node",
      "args": ["/path/to/ffmpeg-mcp/dist/index.js"]
    }
  }
}
```

### Cursor

在 `.cursor/mcp.json` 中：

```json
{
  "mcpServers": {
    "ffmpeg": {
      "command": "node",
      "args": ["/path/to/ffmpeg-mcp/dist/index.js"]
    }
  }
}
```

### Windsurf

在 `~/.codeium/windsurf/mcp_config.json` 中：

```json
{
  "mcpServers": {
    "ffmpeg": {
      "command": "node",
      "args": ["/path/to/ffmpeg-mcp/dist/index.js"]
    }
  }
}
```

### HTTP/SSE 模式（通用 Web 客户端）

```bash
# 启动 SSE 服务
node dist/index.js --transport sse --port 3100

# 启动 Streamable HTTP 服务
node dist/index.js --transport http --port 3100
```

SSE 端点: `http://127.0.0.1:3100/sse`
HTTP 端点: `http://127.0.0.1:3100/mcp`

## 使用示例

配置好客户端后，AI 助手可以直接使用自然语言调用：

- "帮我查看这个视频的信息" → `probe`
- "把这个 AVI 转成 MP4" → `convert`
- "压缩这个视频到更小的体积" → `compress`
- "从视频中提取音频为 MP3" → `extract_audio`
- "截取视频第 30 秒的缩略图" → `thumbnail`
- "裁剪视频从 1 分钟到 3 分钟" → `trim`
- "把这几个视频合并成一个" → `merge`
- "给视频右下角加个水印" → `watermark`
- "把视频片段转成 GIF" → `gif`
- "把视频缩放到 720p" → `resize`
- "把视频 2 倍速播放" → `speed`
- "把视频旋转 90 度" → `rotate`
- "给视频换一个背景音乐" → `add_audio`
- "给视频加上字幕" → `subtitle`
- "把音量调大一倍" → `volume`
- "裁剪视频中间的画面" → `crop`
- "每秒提取一帧图片" → `frames`

## 命令行参数

```
--transport <stdio|sse|http>  传输模式（默认 stdio）
--port <number>               端口号（默认 3100）
--host <string>               绑定地址（默认 127.0.0.1）
```

## License

MIT