MCP 服务器

MCP FFmpeg Helper

一个轻量级服务器，通过模型上下文协议（MCP）将 FFmpeg 的视频处理能力暴露给 AI 助手，支持视频格式转换、音频提取和添加水印等操作。

README

MCP FFmpeg 助手

一个基于 Model Context Protocol (MCP) 的 FFmpeg 辅助工具，提供视频处理功能。

功能概述

MCP FFmpeg 助手是一个轻量级服务器，它通过 MCP 协议将 FFmpeg 的强大功能暴露给 AI 助手。它支持以下视频处理操作：

获取视频文件详细信息
转换视频格式
从视频中提取音频
从图像序列创建视频
裁剪视频
为视频添加水印

安装与配置

前提条件

Node.js (v14+)
FFmpeg (需要安装在系统中并可通过命令行访问) FFmpeg 官方下载页面获取可以使用
```
ffmpeg -version
```
检查是否安装成功

安装步骤

克隆或下载此仓库
安装依赖：
```
npm install
```
构建项目：
```
npm run build
```

配置 MCP

要在 Windsurf 或其他支持 MCP 的应用程序中使用此工具，请将以下配置添加到 MCP 配置文件中：

1.本地配置node服务器

windows:

{
  "mcp-ffmpeg-helper": {
    "command": "cmd",
    "args": [
      "/c",
      "node",
      "path/to/mcp-ffmpeg-helper/build/index.js"
    ]
  }
}

对于 Windows 用户，配置文件通常位于：%APPDATA%/.codeium/windsurf/mcp_config.json

macos:

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

2.使用npm包的方式配置mcp服务器（推荐使用,不需要手动构建node服务器，不用克隆仓库到本地）

windows:

{
  "mcp-ffmpeg-helper": {
    "command": "cmd",
    "args": [
      "/c",
      "npx",
      "@sworddut/mcp-ffmpeg-helper"
    ]
  }
}

macos:

{
  "mcp-ffmpeg-helper": {
    "command": "npx",
    "args": [
      "@sworddut/mcp-ffmpeg-helper"
    ]
  }
}

使用示例

获取视频信息

直接在windsurf控制台输入：请帮我查看"path/to/video.mp4"视频信息

转换视频

直接在windsurf控制台输入：请帮我将"path/to/input.avi"转换为"path/to/output.mp4"

提取音频

直接在windsurf控制台输入：请帮我从"path/to/video.mp4"提取音频到"path/to/audio.mp3"

从图像创建视频

直接在windsurf控制台输入：请帮我从"path/to/images/%05d.jpg"创建视频到"path/to/output.mp4"

裁剪视频

直接在windsurf控制台输入：请帮我裁剪"path/to/input.mp4"到"path/to/output.mp4"，从00:00:00开始，到00:01:00结束

添加水印

直接在windsurf控制台输入：请帮我为"path/to/input.mp4"添加水印到"path/to/output.mp4"，使用"path/to/watermark.png"作为水印，位置在[右下角/左上角/中心等]，透明度[0-1之间的值]

可用工具

1. 获取视频信息 (get_video_info)

获取视频文件的详细信息，包括格式、编解码器、分辨率、帧率等。

参数：

filePath: 视频文件路径

示例：

get_video_info({
  filePath: "path/to/video.mp4"
})

2. 转换视频 (convert_video)

将视频转换为不同格式或应用特定编码选项。

参数：

inputPath: 输入视频文件路径
outputPath: 输出视频文件路径
options: 附加的 FFmpeg 选项（可选）

示例：

convert_video({
  inputPath: "path/to/input.avi",
  outputPath: "path/to/output.mp4",
  options: "-c:v libx264 -crf 23 -preset medium"
})

3. 提取音频 (extract_audio)

从视频文件中提取音频轨道。

参数：

inputPath: 输入视频文件路径
outputPath: 输出音频文件路径
format: 音频格式（如 mp3, aac 等）

示例：

extract_audio({
  inputPath: "path/to/video.mp4",
  outputPath: "path/to/audio.mp3",
  format: "mp3"
})

4. 从图像创建视频 (create_video_from_images)

从图像序列创建视频文件。

参数：

inputPattern: 输入图像模式（如 'img%03d.jpg' 或 'folder/*.png'）
outputPath: 输出视频文件路径
framerate: 帧率（默认：25）
codec: 视频编解码器（默认：libx264）
pixelFormat: 像素格式（默认：yuv420p）
extraOptions: 附加的 FFmpeg 选项（可选）

示例：

create_video_from_images({
  inputPattern: "images/%05d.jpg",
  outputPath: "output.mp4",
  framerate: 30,
  codec: "libx264",
  pixelFormat: "yuv420p"
})

5. 裁剪视频 (trim_video)

将视频裁剪到指定的时间段。

参数：

inputPath: 输入视频文件路径
outputPath: 输出视频文件路径
startTime: 开始时间（格式：HH:MM:SS.mmm 或秒数）
duration: 持续时间（可选，格式同上）
endTime: 结束时间（可选，格式同上）

示例：

trim_video({
  inputPath: "path/to/video.mp4",
  outputPath: "path/to/trimmed.mp4",
  startTime: "00:00:10",
  duration: "00:00:30"
})

6. 添加水印 (add_watermark)

为视频添加图像水印。

参数：

inputPath: 输入视频文件路径
watermarkPath: 水印图像路径
outputPath: 输出视频文件路径
position: 水印位置（topleft, topright, bottomleft, bottomright, center）
opacity: 水印不透明度（0.0-1.0）

示例：

add_watermark({
  inputPath: "path/to/video.mp4",
  watermarkPath: "path/to/logo.png",
  outputPath: "path/to/watermarked.mp4",
  position: "bottomright",
  opacity: 0.7
})

实际使用案例

从图像序列创建 30fps 的 H.264 视频

create_video_from_images({
  inputPattern: "C:/Users/username/images/bear/%05d.jpg",
  outputPath: "C:/Users/username/videos/bear.mp4",
  framerate: 30,
  codec: "libx264",
  pixelFormat: "yuv420p"
})

将视频的前 10 秒裁剪出来

trim_video({
  inputPath: "C:/Users/username/videos/long_video.mp4",
  outputPath: "C:/Users/username/videos/clip.mp4",
  startTime: "0",
  duration: "10"
})