ffmpeg-mcp

ffmpeg / ffprobe を安全な引数渡しで LLM から叩く MCP サーバー

シェル文字列を組み立てずに ffmpeg を駆動する。probe は構造化 JSON で返す。

概要

LLM に ffmpeg -i ... -c:v libx264 ... を文字列として書かせると、エスケープ事故・シェルインジェクション・クォート漏れが起きる。このサーバーは全ての引数を配列で渡し、spawn でシェルを経由せずに起動する。ffprobe は常に -print_format json で叩いて、LLM に渡す前に構造化する。

特徴

処理フロー

sequenceDiagram
    participant LLM
    participant MCP as ffmpeg-mcp (stdio)
    participant FF as ffmpeg / ffprobe

    LLM->>MCP: {action: "probe", input: "in.mp4"}
    MCP->>FF: spawn(ffprobe, [-v error, -print_format json, -show_format, -show_streams, ...])
    FF-->>MCP: stdout (JSON)
    MCP->>MCP: JSON.parse + 間引き
    MCP-->>LLM: {format, streams[], chapters[]}

    LLM->>MCP: {action: "convert", input, output, crf: 23, preset: "medium"}
    MCP->>FF: spawn(ffmpeg, [-n, -i, in.mp4, -crf, 23, -preset, medium, out.mp4])
    FF-->>MCP: exit_code / stdout / stderr(tail) / duration_ms
    MCP-->>LLM: JSON

インストール

git clone https://github.com/cUDGk/ffmpeg-mcp.git
cd ffmpeg-mcp
npm install
npm run build

ffmpeg と ffprobe が PATH にある事が前提。別パスにある場合は FFMPEG_PATH / FFPROBE_PATH で明示する。

使い方

Claude Code に登録

claude mcp add ffmpeg -- node <install-dir>/dist/index.js

環境変数

FFMPEG_MCP_ALLOW_ROOTS の例:

# Windows (PowerShell): 区切りは ";"
$env:FFMPEG_MCP_ALLOW_ROOTS = "C:\Users\me\videos;D:\renders"

# Linux / macOS: 区切りは ":"
export FFMPEG_MCP_ALLOW_ROOTS="/home/me/videos:/srv/renders"

セキュリティ

• 既定で出力ファイルは上書きしない (ffmpeg -n)。意図的に上書きしたい場合は overwrite: true を渡す（ffmpeg -y）。

• run / convert.extra_args は無検査ではない。ffmpeg のプロトコルプレフィックス (concat:, subfile:, http:, file:, tee:, data: 等) や、ファイルを読む系のフィルタ (movie=..., subtitles=..., drawtext=...textfile=..., sendcmd=...) や、-protocol_whitelist 上書き / -f tee は拒否する。それ以外の動作については LLM 任せにせず、ホスト側でも FFMPEG_MCP_ALLOW_ROOTS を設定する事を推奨する。

• 全ての -i 呼び出しに -protocol_whitelist file,crypto,data を強制注入する（HTTP/RTMP/RTSP 経由の任意 URL fetch を遮断する）。

呼び出し例

未知ファイルの確認 → 中央 10 秒を切り出し → H.264 に再圧縮:

{"action": "probe", "input": "C:/tmp/raw.mkv"}

{"action": "trim", "input": "C:/tmp/raw.mkv", "output": "C:/tmp/clip.mkv",
 "start": "00:01:00", "duration": 10}

{"action": "convert", "input": "C:/tmp/clip.mkv", "output": "C:/tmp/out.mp4",
 "video_codec": "libx264", "crf": 23, "preset": "medium",
 "audio_codec": "aac", "audio_bitrate": "128k"}

サムネイル 4 枚（0 / 10 / 20 / 30 秒）:

{"action": "thumbnail", "input": "in.mp4", "output": "t0.jpg", "time": 0, "size": [640, 360]}
{"action": "thumbnail", "input": "in.mp4", "output": "t1.jpg", "time": 10, "size": [640, 360]}
{"action": "thumbnail", "input": "in.mp4", "output": "t2.jpg", "time": 20, "size": [640, 360]}
{"action": "thumbnail", "input": "in.mp4", "output": "t3.jpg", "time": 30, "size": [640, 360]}

ラウドネス正規化 (podcast / YouTube 公開用):

{"action": "loudnorm", "input": "raw.wav", "output": "normalized.m4a",
 "target_i": -14, "target_tp": -1.0, "target_lra": 7,
 "audio_codec": "aac", "audio_bitrate": "192k"}

ロゴ透かし (右上 10% サイズ、60% 透過):

{"action": "watermark", "input": "in.mp4", "output": "out.mp4",
 "watermark_path": "logo.png",
 "position": "top-right", "margin": 20,
 "watermark_scale": 0.1, "opacity": 0.6}

2x 早回し:

{"action": "speed", "input": "in.mp4", "output": "2x.mp4", "speed_factor": 2.0}

複数動画を一括処理 (最初の失敗で中断):

{"action": "batch", "stop_on_error": true, "jobs": [
  {"action": "trim", "input": "raw.mp4", "output": "clip.mp4", "start": 10, "duration": 30},
  {"action": "convert", "input": "clip.mp4", "output": "final.mp4", "video_codec": "libx264", "crf": 20},
  {"action": "thumbnail", "input": "final.mp4", "output": "poster.jpg", "time": 5}
]}

run で完全制御（例: フィルタ複雑グラフ）:

{"action": "run", "args": [
  "-y", "-i", "in.mp4",
  "-filter_complex", "[0:v]scale=1280:720,fps=30[v]",
  "-map", "[v]", "-map", "0:a",
  "-c:v", "libx264", "-crf", "20",
  "out.mp4"
]}

設計メモ

• 意図ベースのアクション（convert_to_mp4 等）を増やさない。増やしても結局 extra_args で逃げるだけで、LLM に覚えさせる面が増える。アクションは処理のカテゴリ単位（convert / trim / concat / thumbnail）に留める。

• stderr は末尾 16 KB だけ残す。ffmpeg は 1 回の実行で数 MB のログを吐く事があり、LLM のコンテキストを焼き尽くす。

• 相対パスは CWD から resolve。LLM が相対パスを渡しても意図通りの場所に書き出される。

• タイムアウト既定 10 分。長時間エンコードは timeout で上書き。

v0.3.1 修正

バグ修正:

• batch の watermark ジョブで watermark_path → watermark / watermark_scale → scale のフィールドマッピングが欠落していた問題を修正（ウォーターマーク画像と scale が常に無視されていた）。

• batch の speed ジョブで speed_factor → speed のフィールドマッピングが欠落していた問題を修正（speed が undefined になり Number.isFinite チェックで必ずエラーになっていた）。

• README の mermaid ダイアグラムで -y と表示されていたのを -n (no-clobber デフォルト) に修正。

v0.3.0 修正

セキュリティ・バグ・UX を一括で改修したリリース。

セキュリティ:

• run / convert.extra_args の引数を assertSafeFfmpegArgs() で検査。ffmpeg プロトコルプレフィックス・ファイル読み取り系フィルタ・-protocol_whitelist 上書き・-f tee を拒否。

• 全ての -i 呼び出しに -protocol_whitelist file,crypto,data を強制注入。

• safeInputPath() を全アクションの入力に適用（Windows ドライブレター C:\... は許可、http: / concat: 等は拒否）。

• 既定値を -y (force overwrite) → -n (no clobber) に変更。明示的に overwrite: true を渡した時だけ上書きする。

• FFMPEG_MCP_ALLOW_ROOTS で出力先をディレクトリ単位でホワイトリスト可能。

• FFMPEG_MCP_MAX_JOBS で batch.jobs[] の長さに上限。

• concat のリストファイルに改行を含むエントリを拒否（行ベースパーサを破壊する為）。

バグ修正:

• stdout / stderr を Buffer.concat() で組み立てる様に変更（チャンク境界で UTF-8 が壊れる問題を解消）。

• stdout にも 8 MiB の上限を導入。

• loudnormPass1 の stderr を切り詰めない。loudnorm の JSON ブロックが落ちる事があった。

• loudnormPass1 が timeout を尊重していなかった問題を修正。

• concat() の mkdtempSync を try の中に移動。例外時の temp dir リーク防止。

• proc.stdout / proc.stderr に error リスナを追加（Windows での EPIPE 未処理を防止）。

• killProc を非同期化（execFileSync でイベントループを止めない）。

• speed で setpts=Infinity*PTS を防ぐバリデーション。

• version の戻り値が空 / 非 0 終了時に isError: true を立てる様に。

• tsconfig.json に noUncheckedIndexedAccess: true。

UX:

• ツール説明に watermark / loudnorm / speed / batch を追記。

• thumbnail のデフォルト time をドキュメント通りの 00:00:01 に。

• batch.jobs[].action を厳密な enum に。

• batch で 1 件でも失敗したら全体の isError を立てる。

• extra_args が convert 専用である事を明記。

v0.2.1 修正

一部の MCP クライアント (Claude Code の LLM ツール使用パス等) が object / array 引数を JSON 文字列化してからサーバーに渡す挙動があり、extra_args / args / input_paths / resolution / size / jobs が文字列で届くと zod バリデーションで落ちるか、args.push(...p.extra_args) で文字列を spread して 1 文字ずつ ffmpeg の引数に混入する等の事故が起きていた。

修正内容:

• extra_args / args / input_paths / resolution / size / jobs の zod schema を z.union([<本来の型>, z.string()]) に緩和

• coerceArray() / coerceObject() ヘルパを追加し、文字列で届いた場合は JSON.parse で配列 / オブジェクトに戻してから使用

• batch の各 job 内部のネスト配列 (extra_args / resolution / size / args / input_paths) も coerce してから dispatch

Attribution

• FFmpeg © FFmpeg developers（LGPL/GPL）— 本 MCP はラッパーであり FFmpeg 本体のライセンスに従う

• Model Context Protocol — 仕様・SDK

ライセンス

MIT License © 2026 cUDGk — 詳細は LICENSE を参照。