Mcp Ffmpeg Helper

MCP FFmpeg Helper

Model Context Protocol（MCP）に基づく FFmpeg 補助ツールで、動画処理機能を提供します。

機能の概要

MCP FFmpeg Helper は、MCP プロトコルを通じて FFmpeg の強力な機能を AI アシスタントに提供する軽量なサーバーです。以下の動画処理操作をサポートしています。

• 動画ファイルの詳細情報を取得
• 動画形式を変換
• 動画から音声を抽出
• 画像シーケンスから動画を作成
• 動画をトリミング
• 動画にウォーターマークを追加
• 音声ファイルをトリミング
• 動画からフレームを画像シーケンスとして抽出

インストールと設定

前提条件

• Node.js（v14+）
• FFmpeg（システムにインストールし、コマンドラインからアクセスできる必要があります） FFmpeg 公式ダウンロードページから入手できます 以下を使用して

  ffmpeg -version
  

  インストールが成功したか確認できます

インストール手順

1. このリポジトリをクローンまたはダウンロードします
2. 依存関係をインストールします：

   npm install
   

3. プロジェクトをビルドします：

   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の値]にしてください

音声をトリミング

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_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
})

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' は2フレームごと、'1/30' は30秒ごとに1フレームを抽出）
• 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 License