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 验证）

安装

npm install
npm run build

客户端配置

Claude Code

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

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

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

Cursor

在 .cursor/mcp.json 中：

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

Windsurf

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

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

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

# 启动 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