星战科技xingzhan.cloud
返回市场
mcp-ffmpeg辅助工具

mcp-ffmpeg辅助工具

作者：sworddut22 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

MseeP.ai 安全评估徽章

MCP FFmpeg 辅助工具

基于模型上下文协议（MCP）的FFmpeg辅助工具，提供视频处理功能。

<a href="https://glama.ai/mcp/servers/@sworddut/mcp-ffmpeg-helper"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=268992075,332472688&fm=3081&app=3081&f=PNG?w=760&h=400" alt="FFmpeg 辅助工具 MCP 服务器" /> </a>

功能概述

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

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

安装与配置

预备条件

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

安装步骤

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

配置 MCP

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

1. 本地配置节点服务器

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服务器（推荐，无需手动构建节点服务器，无需将仓库克隆到本地）

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之间

裁剪音频

直接在Windsurf控制台输入： 请帮我裁剪'path/to/input.mp3'到'path/to/output.mp3'，从00:00:10开始持续30秒

提取视频帧

直接在Windsurf控制台输入： 请帮我从'path/to/video.mp4'提取帧到'path/to/frames'文件夹，使用PNG格式以保持最高质量

可用工具

1. 获取视频信息 (get-video_info)

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

参数

  • filePath: 视频文件路径

示例

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

2. 转换视频 (convert_fideo)

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

参数

  • 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. 提取音频

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

参数

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

示例

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

4. 从图像创建视频 (creat_fideo_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. 添加水印 (addw_watermark)

向视频添加图像水印。

参数

  • inputPath: 输入视频文件路径
  • watermarkPath: 水印图像路径
  • outputPath: 输出视频文件路径
  • position: 水印位置（左上、右上、左下、右下、中心）
  • 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
})

7. 裁剪音频 (trim-audio)

将音频文件裁剪到指定的时间段。

参数

  • inputPath: 输入音频文件路径
  • outputPath: 输出音频文件路径
  • startTime: 开始时间（格式：HH:MM:SS.mmm或秒）
  • duration: 持续时间（可选，格式同上）
  • endTime: 结束时间（可选，格式同上）
  • format: 音频格式（如mp3、aac等，可选）

示例

trim_audio({
  inputPath: "path/to/audio.mp3",
  outputPath: "path/to/trimmed.mp3",
  startTime: "00:00:10",
  duration: "00:00:30",
  format: "mp3"
})

8. 提取视频帧 (extract_frames)

从视频中提取帧并保存为一系列图像。

参数

  • inputPath: 输入视频文件路径
  • outputDir: 输出图像目录（默认：'output'）
  • frameRate: 帧提取速率（例如'1'每帧提取，'0.5'每两帧提取，'1/30'每30秒提取一帧）
  • format: 输出图像格式（jpg、png等，默认：jpg）
  • quality: 图像质量（1-100，默认：95）
  • startTime: 开始提取的时间点（可选）
  • duration: 提取持续时间（可选）

示例

extract_frames({
  inputPath: "path/to/video.mp4",
  outputDir: "path/to/frames",
  frameRate: "1",
  format: "png",
  quality: 99
})

实际使用案例

从图像序列创建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"
})

提取高质量视频帧

extract_frames({
  inputPath: "C:/Users/username/videos/movie.mp4",
  outputDir: "C:/Users/username/frames",
  frameRate: "1",
  format: "png",
  quality: 99
})

裁剪音频文件的特定部分

trim_audio({
  inputPath: "C:/Users/username/music/song.mp3",
  outputPath: "C:/Users/username/music/clip.mp3",
  startTime: "01:30",
  duration: "00:30",
  format: "mp3"
})

故障排除

  • 确保FFmpeg正确安装并添加到系统PATH
  • 检查文件路径是否正确，特别是在Windows系统中使用反斜杠（\）
  • 如果遇到权限问题，请确保应用程序有权访问指定的文件和目录
  • 对于复杂的FFmpeg命令，可以使用options或extraOptions传递额外的命令行选项
  • 如果提取的图像质量较差，尝试使用PNG格式并设置更高的质量值（95-99）

开发

项目结构

该项目采用模块化结构，便于维护和扩展：

  • src/index.ts - 主入口文件，设置MCP服务器
  • src/utils/file.ts - 文件操作相关的工具函数
  • src/utils/ffmpeg.ts - 与FFmpeg相关的实用函数
  • src/tools/definitions.ts - 工具定义
  • src/tools/handlers.ts - 工具处理函数实现

调试

由于MCP服务器通过标准输入/输出进行通信，调试可能较为困难。建议使用控制台日志进行调试：

console.log("调试信息");

扩展功能

要添加新的FFmpeg功能，请修改以下文件：

  1. 在src/tools/definitions.ts中定义新的工具
  2. 在src/tools/handlers.ts中添加相应的实现
  3. 重新构建项目：npm run build

许可证

MIT 许可证