mcp-ffmpeg-tools

mcp-ffmpeg-tools

LLM（大規模言語モデル）が FFmpeg コマンドを実行し、実行結果を受け取り、FFmpeg のソースコードと照合してコマンドを検証できるように設計された、オープンソースの Python MCP（Model-Command Protocol）サーバーです。

前提条件

mcp-ffmpeg-tools をインストールする前に、システムに FFmpeg がインストールされている必要があります。

Windows

1. ffmpeg.org から FFmpeg をダウンロードします
2. アーカイブを任意の場所に展開します
3. bin ディレクトリをシステムの PATH に追加します

macOS

brew install ffmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

Linux (Fedora)

sudo dnf install ffmpeg

機能

• MCP インターフェースを通じて FFmpeg コマンドを実行します
• 詳細な実行結果とエラーメッセージを受け取ります
• コマンド修正のために FFmpeg のソースコードにアクセスします
• クロスプラットフォームに対応しています（Windows、macOS、Linux）
• uv を使用して環境を管理します

インストール

1. リポジトリをクローンします：

git clone https://github.com/gamhoi/mcp-ffmpeg-tools.git
cd mcp-ffmpeg-tools

2. uv を使用してインストールします：

uv venv
uv pip install -e .

インストールプロセスでは、次の処理が行われます。

1. FFmpeg がインストールされ、システムの PATH からアクセスできることを確認します
2. 検証用の対応する FFmpeg ソースコードをダウンロードします
3. Python パッケージとその依存関係をインストールします

FFmpeg が見つからない場合、またはソースコードのダウンロードに失敗した場合、インストールは失敗します。

使用方法

Claude Desktop での使用

次の設定を Claude Desktop の設定に追加します。

{
    "mcpServers": {
        "mcp-ffmpeg-tools": {
            "command": "uv",
            "args": [
                "--directory",
                "PATH_TO/mcp-ffmpeg-tools",
                "run",
                "ffmpeg-tools"
            ]
        }
    }
}

テストの実行

uv run python3 client/test.py

プロンプトの例

基本プロンプト

Help me perform media conversion tasks using FFmpeg. You can:
- use tool:execute_ffmpeg to run FFmpeg commands
- use tool:execute_ffprobe to inspect results (e.g., resolution, bitrate)
- use tool:get_screenshot to inspect results (e.g., video layout, quality)
- use tool:ls_ffmpeg_source_code and tool:get_ffmpeg_source_code to validate commands using FFmpeg source code

動画と音声を抽出する

Extract all media streams from the file 'YOU_FILE_PATH' and save outputs to 'YOU_OUTPUT_PATH'

2 つの動画を重ねる

Overlay file1 'YOU_FILE_PATH_1' and file2 'YOU_FILE_PATH_2', using file1 as the background. Scale file2 down to half its original resolution and position it at the top-right corner of file1. Save the output to 'YOUR_OUTPUT_PATH'.

Docker で実行する

Docker を使用して、MCP FFmpeg Tools を HTTP モードで実行できます。 これにより、クライアントが使用できるように MCP API（/mcp）を HTTP ポートで公開できます。

オプション 1 — Docker Hub からプルする

Docker Hub から公式イメージを直接プルして実行できます。

docker pull gamhoi/mcp-ffmpeg-tools:latest

ポート 8000 で実行します。

docker run -d -p 8000:8000 gamhoi/mcp-ffmpeg-tools:latest --port 8000

次の設定を Claude Desktop の設定に追加します。

{
    "mcpServers": {
        "mcp-ffmpeg-tools-http": {
            "type": "streamableHttp",
            "url": "http://localhost:8000/mcp"
        }
    }
}

注：デフォルトの URL http://localhost:8000/mcp は、MCP サーバーがローカルで実行されていることを前提としています。 リモート環境またはネットワーク環境で実行している場合は、localhost をホストの IP アドレスまたはドメイン名に置き換えてください。

オプション 2 — ローカルでビルドする

Dockerfile からビルドする場合：

docker build -t mcp-ffmpeg-tools .

ローカルファイルへのアクセス

デフォルトでは、コンテナ内の ffmpeg は Docker の外部にあるローカルファイルにアクセスできません。 ローカルの動画を処理できるようにするには、ホストのディレクトリをコンテナにマウントする必要があります。

例：

docker run -d -p 8000:8000 -v /local_media:/media gamhoi/mcp-ffmpeg-tools:latest --port 8000

この例では：

• ローカルの動画ファイルを次の場所に置けます：/local_media/sample.mp4
• コンテナ内では、同じファイルに次の場所からアクセスできます：/media/sample.mp4

そのため、LLM にローカルファイルの処理を依頼する際は、次のようにします。

Extract all media streams from the file /media/sample.mp4 and save outputs to /media/