FFmpeg MCP Server

ffmpeg-mcp-server

AI ツールから FFmpeg と FFprobe を利用して、動画や音声をローカルで処理できるようにする Model Context Protocol（MCP）サーバーです。

Apple Silicon のハードウェアエンコーディングに対応し、視覚機能を備えたモデルに画像プレビューを直接返します。

---

このプロジェクトについて

AI エージェントがメディアを処理すると、無効なフラグや構文エラー、互換性のないピクセル形式を誤って出力することがよくあります。

このサーバーは、Zod スキーマを使用する 13 個の型付きツールを提供します。AI がパラメーター（例：{ inputPath: "video.mov", preset: "web_mp4" }）を渡すと、サーバーが有効な FFmpeg コマンドをローカルで実行します。

---

主な機能

• ハードウェアエンコーディング： macOS で VideoToolbox を使用し、CPU 使用率を抑えながらエクスポートを高速化します。
• 画像レスポンス： Base64 画像を返すため、視覚モデルがサムネイルや波形を確認できます。
• ソーシャルメディア向けフォーマット： 横向き動画を、ぼかした背景の余白を追加した 9:16 の縦向き動画に変換します。
• 画面分割： 2 本の動画を上下に並べて、Reels や TikTok 向けに出力します。字幕や音声のミキシングも選択できます。
• 無音部分の削除： 音声録音の間を検出してトリミングします。

---

同梱ツール（全13種類）

ツール	説明	主なパラメーター
media_probe	ffprobe でメディアファイルを調査します。メタデータ、ストリーム、コーデック、解像度、再生時間を JSON 形式で返します。	inputPath
media_convert	動画や音声の形式を変換します。Web MP4、WebM、アニメーション GIF 用のプリセットが含まれています。	inputPath、outputPath、preset、crf、resolution、fps、hardwareAcceleration
trim_media	ストリームコピーまたは再エンコードを使用して、動画または音声ファイルから一部分を切り出します。	inputPath、outputPath、startTime、endTime、duration、accurateReencode
extract_audio	動画から音声トラックを抽出します。Whisper の音声認識用に、16kHz モノラル WAV のプリセットが含まれています。	inputPath、outputPath、format、bitrate
extract_thumbnail	指定したタイムスタンプまたは中間地点の静止画像を取得します。ビジョンモデル用の base64 画像データを返します。	inputPath、outputPath、timestamp、resolution、includeBase64
compress_video	目標サイズ（GitHub の PR では 10MB 未満、Discord では 25MB 未満など）に収まるよう動画を圧縮します。	inputPath、outputPath、targetSizeMB、preset、crf、maxWidth、hardwareAcceleration
reformat_aspect_ratio	ぼかした境界線または中央クロップを使用して、動画の比率を縦長の 9:16、正方形の 1:1、またはポートレートの 4:5 に変更します。	inputPath、outputPath、targetRatio、mode、blurAmount、padColor
create_split_screen	2本の動画を上下（9:16 の Reels／TikTok）または左右に並べ、音声ミキシングと字幕を追加します。	firstVideoPath、secondVideoPath、outputPath、layout、audioSource、subtitlesPath
trim_silence	録音の無音部分を検出して削除します。再生時間と削減された秒数を報告します。	inputPath、outputPath、mode、thresholdDb、minDurationSeconds
concat_media	ストリームコピーまたは再エンコードを使用して、複数の動画または音声ファイルを順番につなげます。	inputPaths、outputPath、mode
generate_waveform	波形画像を PNG 形式で生成します。ビジョンモデル用の base64 画像データを返します。	inputPath、outputPath、width、height、color、scale、includeBase64
add_subtitles	動画を再エンコードせずに、SRT または VTT の字幕トラックを動画ファイルに埋め込みます。	videoPath、subtitlesPath、outputPath、language、title
change_speed	ピッチ補正を行いながら、再生速度（2倍速や0.5倍のスローモーションなど）を調整します。	inputPath、outputPath、speed、muteAudio

---

必要条件

• Node.js >= 18.0.0
• FFmpeg と FFprobe がローカルにインストールされていること：
  • macOS： brew install ffmpeg
  • Linux（Ubuntu/Debian）： sudo apt update && sudo apt install ffmpeg
  • Windows： winget install Gyan.FFmpeg または choco install ffmpeg

---

インストール

クイックスタート（Claude Desktop、Cursor、Antigravity）

npx で直接実行できます（手動でのクローンやビルドは不要です）：

{
  "mcpServers": {
    "ffmpeg": {
      "command": "npx",
      "args": ["-y", "@ash_j1997/ffmpeg-mcp-server"]
    }
  }
}

設定ファイルの場所：

• Claude Desktop（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）： %APPDATA%\Claude\claude_desktop_config.json
• Antigravity IDE： ~/.gemini/config/mcp_config.json
• Cursor / Windsurf： コマンド npx、引数 ["-y", "@ash_j1997/ffmpeg-mcp-server"] を指定して、stdio サーバーとして追加します。

---

ローカル開発

1. 依存関係をインストールします：

   npm install
   

2. TypeScript をビルドします：

   npm run build
   

3. テストを実行します：

   node test-tools.js
   

---

ライセンス

MIT © Ashutos1997