videoworker

videoworker MCP

AI エージェントに FFmpeg を使わせましょう。ローカルメディアをアップロードし、リモートジョブを実行して、結果を保存できます。

videoworker の動画、音声、画像処理 API に接続する、MIT ライセンスのローカル stdio MCP コネクターです。標準の FFmpeg 引数を指定すれば、ワーカーが実行します。ローカルに FFmpeg をインストールする必要はありません。

無料で始める · ホスト型 MCP · REST API · リリース · Glama に掲載

接続方法を選択

	ローカルコネクター — このリポジトリ	ホスト型 MCP
おすすめの用途	ローカルファイルのアップロードとダウンロード	Python をインストールせずに接続
トランスポート	stdio	Streamable HTTP
サインイン	非公開ファイルに保存するスコープ付き API キー	ブラウザーでのログインと OAuth 同意
ローカルファイルへのアクセス	選択したフォルダー内の名前付きメディア	なし。先にウェブまたは REST 経由でアップロードしてください
セットアップ	以下のクイックスタート	ホスト型セットアップガイド

どちらも同じアカウントと利用枠を使用します。コネクターは無料ソフトウェアです。ホスト型の処理には現在のプランと制限が適用されます。無料アカウントには、毎月少量の利用枠が付与されます。Starter のローンチ特典とその利用可能状況については、料金をご確認ください。Free の利用にトライアルは必要ありません。

クイックスタート

1. インストール — チェックアウトや Git は不要です

Python 3.12 以降が必要です。バージョン指定のリリースホイールをインストールします。

python -m pip install "https://github.com/AzadKurt/videoworker-mcp/releases/download/v0.1.0/videoworker_mcp-0.1.0-py3-none-any.whl"
python -m videoworker_mcp --version

Windows では、必要に応じて python の代わりに py -3.12 を使ってください。macOS/Linux では、コマンドが python3 の場合があります。MCP 設定でも同じ Python インストールを使用してください。次のコマンドでフルパスを表示できます。

python -c "import sys; print(sys.executable)"

Git がインストールされている場合の代替手順：

python -m pip install "git+https://github.com/AzadKurt/[email protected]"

このパッケージはまだ PyPI に登録されていません。このリリースでは pip install videoworker-mcp は使用しません。

2. ワークスペースと非公開のキー・ファイルを作成する

ワークスペースにサインインします。API キーのページで、8 つすべてのツールに対して usage:read、files:write、jobs:read、jobs:write、outputs:read の権限を持つキーを作成します。自分のユーザーだけがアクセスできるファイルに、プレーンテキストで保存してください。macOS/Linux では chmod 600 /absolute/path/to/key を実行します。Windows ではユーザープロファイル内に保存し、ファイルのアクセス許可を自分だけに制限してください。

uploads フォルダーと downloads フォルダーを作成します。どちらも存在し、絶対パスを使用している必要があります。uploads には許可されたメディアだけを置き、キー・ファイルは別の場所に保管してください。キーをチャットや共有クライアント設定に貼り付けないでください。

3. クライアント設定を追加する

Python とファイル／フォルダーのパスを自分のものに置き換えてください。**既存の設定にエントリーを追加し、ほかのサーバーはそのまま残してください。**値はパスであり、秘密情報ではありません。保存したら、クライアントを再起動するか、設定を再読み込みしてください。

Codex

~/.codex/config.toml に追加します。

[mcp_servers.videoworker]
command = "/absolute/path/to/python"
args = ["-m", "videoworker_mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 960

[mcp_servers.videoworker.env]
VIDEO_WORKER_API_KEY_FILE = "/absolute/path/to/videoworker.key"
VIDEO_WORKER_UPLOAD_ROOT = "/absolute/path/to/uploads"
VIDEO_WORKER_DOWNLOAD_ROOT = "/absolute/path/to/downloads"

Windows では、C:/Users/YOU/media/uploads のようなスラッシュ区切りのパスを使用できます。編集して使えるファイル：Windows / macOS と Linux。併用する場合は、ホスト型接続の名前を videoworker_remote のままにしてください。

Claude Desktop

設定 → 開発者 → 設定を編集を開き、次を追加します。

{
  "mcpServers": {
    "videoworker": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "videoworker_mcp"],
      "env": {
        "VIDEO_WORKER_API_KEY_FILE": "/absolute/path/to/videoworker.key",
        "VIDEO_WORKER_UPLOAD_ROOT": "/absolute/path/to/uploads",
        "VIDEO_WORKER_DOWNLOAD_ROOT": "/absolute/path/to/downloads"
      }
    }
  }
}

編集して使えるファイル：Windows / macOS と Linux。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）で同じ JSON 構造を使用します。Cursor の MCP 設定でサーバーを有効にしてください。 すぐに編集できるファイル：Windows / macOS and Linux。

例では、ドキュメントに記載されている stdio 設定形式を使用しています。実際の MCP SDK の検出はテスト済みですが、すべてのデスクトップアプリ／バージョンを手動でテストしたと主張するものではありません。

4. 小さなジョブを試す

小さな clip.mp4 を uploads に入れて、エージェントに次のように依頼します。

まず videoworker の利用枠を確認してください。設定済みの uploads フォルダーにある clip.mp4 のアップロードを許可します。最初の 1 秒にトリミングし、MP4 として圧縮してください。 実行時間の上限を 10 秒にして、ジョブを 1 つ作成してください。再試行する場合に備えて request_id を保持し、ステータスを確認する際は少なくとも 1 秒間隔を空けてください。成功した結果は、downloads フォルダーに clip-small.mp4 として保存してください。何も削除しないでください。

フロー：get_usage → upload_file → create_job → get_job → download_result。 ジョブ引数の例を参照してください。入力ファイル ID を置き換え、ジョブを実行するたびに新しい UUID を生成してください。

複数の入力

ワークフローのレシピでは、クリップの結合、画像／ロゴの追加、サウンドトラックの置き換えについて説明しています。それぞれに入力順、動作に関する注意事項、すぐに編集できる MCP JSON ファイルが含まれています。同じレシピがウェブサイトにも掲載されており、REST と MCP 用のコピーボタンを利用できます。

ツール

ツール	目的	API キーのスコープ
get_usage	利用枠、予約、ストレージ	usage:read
list_jobs	最近の所有ジョブ	jobs:read
upload_file	許可されたローカルメディアをアップロード	files:write
create_job	安定した再試行 UUID を使用する FFmpeg ジョブ	jobs:write
get_job	ジョブの状態と出力メタデータ	jobs:read
download_result	出力を新しいローカルファイルに保存	jobs:read、outputs:read
cancel_job	キャンセルを要求し、終了を確認	jobs:write
delete_job_outputs	要求された場合に結果を削除	jobs:write

設定とトラブルシューティング

環境変数	値
VIDEO_WORKER_API_KEY_FILE	秘密のプレーンテキストキー ファイルへの絶対パス
VIDEO_WORKER_UPLOAD_ROOT	許可されたメディアが格納された既存の絶対パスのフォルダー
VIDEO_WORKER_DOWNLOAD_ROOT	既存の絶対パスの保存先フォルダー
VIDEO_WORKER_API_URL	任意。デフォルトは https://videoworker.dev です

VIDEO_WORKER_API_KEY は非公開のプロセス環境でサポートされており、ファイルより優先されます。共有設定やコマンドラインには絶対に記載しないでください。 カスタムオリジンには HTTPS が必要です。ただし、開発用の明示的なループバック HTTP は除きます。

• ENOENT / サーバーが見つからない： シェルエイリアスではなく、上に表示された Python のフルパスを使用してください。GUI アプリケーションでは PATH が異なる場合があります。
• 設定エラー： ターミナルで同じ変数を設定し、python -m videoworker_mcp --check を実行してください。ローカル設定のみを検証し、API 呼び出しや認証情報／利用枠の確認は行いません。ヘルプ／バージョンの確認にキーは不要です。
• 未認証／アクセス拒否： ダッシュボードでキー、スコープ、アカウントを確認してください。サポートメッセージで認証情報を送信しないでください。
• ファイルが拒否される： パスや URL ではなく、単純なファイル名を指定してください。ローカルで使用できる拡張子は、mp4、mp3、wav、webm、gif、png、jpg、jpeg、mkv、mov、ogg、flac です。リンクされたフォルダーやシンボリックリンク／ジャンクションは拒否されます。
• 転送が遅い： アップロード／ダウンロードには、ネットワーク操作ごとに最大 15 分かかる場合があります。サポートされている場合は、適切なツール呼び出しタイムアウトを設定してください。ツール呼び出しを終了しても、受け付けられた処理ジョブはキャンセルされません。

データと再試行

サービスでは、アカウントの所有権、利用枠、ファイル制限、有効期限が適用されます。 ローカルプロセスは OS ユーザーとして実行されます。フォルダー制限はアプリケーションによるガードであり、オペレーティングシステムのサンドボックスではありません。ローカルの FFmpeg は同梱されておらず、必要もありません。

ダウンロード時にファイルが上書きされることはなく、エージェントが指定した出力 URL をたどることもありません。宣言された出力サイズの上限は 1 GiB です。サイズのない従来のメタデータには、50 MiB のフォールバック上限が適用されます。転送では、動画全体をメモリに読み込まず、ストリーミングします。

ジョブを再試行する場合は、同じ UUID の request_id と同一の引数を保持してください（48 時間）。応答が不確かな場合でも、処理が成功している可能性があります。アップロードは冪等ではありません。ポーリングは 1 秒に 1 回より速く行わず、有効期限が切れる前にダウンロードしてください。キャンセル／削除が完了するのは、サーバーの確認後のみです。課金／管理者権限は必要ありません。

開発

python -m pip install '.[dev]'
python -m pytest -q
python -m ruff check .
python -m ruff format --check .

テストでは、小規模な制御済み HTTP フィクスチャと実際の MCP SDK の検出を使用します。リリースチェック、依存関係のライセンス、セキュリティに関する報告を参照してください。

ライセンスとサポート

コネクターは MIT ライセンスです。ホスト型の処理と非公開バックエンドは別個のものです。GitHub の課題または [email protected] までお問い合わせください。

設定リファレンス：Codex、 Claude Desktop、 Cursor。