ffmpeg-micro

@ffmpeg-micro/mcp-server

Model Context Protocol サーバーです。AI エージェント — Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、その他の MCP 互換クライアント — が、FFmpeg Micro REST API を通じて動画のトランスコードを作成、監視、ダウンロードできます。

できること

FFmpeg Micro の公開 API に対応するツールを提供します。

ツール	機能
transcode_video	1つ以上の入力動画（gs:// または https://）からトランスコードジョブを作成します。品質／解像度のプリセットと、FFmpeg オプションの直接指定に対応しています。
get_transcode	単一ジョブの現在の状態を取得します。
list_transcodes	任意の status、page、limit、since、until フィルターを指定してジョブを一覧表示します。
cancel_transcode	保留中または処理中のジョブをキャンセルします。
get_download_url	完了したジョブの出力ファイル用に、有効期間10分の署名付き HTTPS URL を生成します。
transcode_and_wait	便利な一括処理です。ジョブを作成し、完了するまでポーリングして、署名付きダウンロード URL を1回の呼び出しで返します。
request_upload_url	ダイレクトアップロードフローのステップ1です。ホストがファイルのバイトデータを PUT するための、事前署名付き HTTPS URL を返します。
confirm_upload	ダイレクトアップロードフローのステップ2です。トランスコード／文字起こしの入力としてすぐに使える、最終的な gs:// URL とプローブメタデータを返します。
run_blueprint	ブループリントの実行を開始します。ブループリントは、あらかじめ構築された動画ワークフロー（字幕付け、サイズ変更、ウォーターマーク、広告など）です。
get_blueprint_run	ブループリント実行のステータス、ステップ、出力 URL を取得します（複数出力のブループリントでは、ラベル付きの outputs が返されます）。
run_blueprint_and_wait	便利な一括処理です。ブループリントの実行を開始し、完了、失敗、またはトランスクリプトの確認待ちで一時停止するまでポーリングします。
continue_blueprint_run	awaiting_review で一時停止している caption-video の実行を、承認済みの SRT トランスクリプトを送信して再開します。

ブループリント

ブループリントは、POST /v1/blueprints/{slug}/runs で実行できる、あらかじめ構築されたワークフローです。各ブループリントの入力フィールドについては、ツールの説明を参照してください。注意事項：

• ほとんどのブループリントは FFmpeg レーンで実行され、プランのコンピューティング時間を消費します（トークンは消費しません）。生成系ブループリント（product-ad）はトークンを消費します。402 insufficient_tokens が返された場合は、アカウントにトークンパックが必要です（ダッシュボード）。
• caption-video はトランスクリプト（srt_text）を含む awaiting_review 状態で一時停止するため、エージェントはレンダリング前に内容を確認・編集できます。continue_blueprint_run で再開してください。
• 複数出力のブループリント（listing-kit、hook-variants）は、{label, url} の配列である outputs を返します。存在する場合は output_url よりこちらを優先してください。
• 出力 URL の署名の有効期間は10分です。新しいリンクを取得するには、実行情報を再取得してください。

ローカルファイルのアップロード

request_upload_url と confirm_upload の組み合わせを使うと、生の API キーや gs:// URL を扱わずに、MCP ホストから FFmpeg Micro のストレージバケットへローカルファイルをアップロードできます。

1. ホストが {filename, contentType, fileSize} を指定して request_upload_url を呼び出すと、有効期間の短い事前署名付き HTTPS URL が返されます。
2. ホストが同じ Content-Type を指定して、その URL にファイルのバイトデータを PUT します。
3. ホストが {filename: <storage filename from step 1>, fileSize} を指定して confirm_upload を呼び出すと、最終的な gs://... の fileUrl が返されます。
4. ホストはその fileUrl を transcribe_audio／transcode_video／transcode_and_wait に渡します。

クイックスタート

プロジェクトの .mcp.json（または MCP クライアントの設定）に次を追加します。

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

これで完了です。AI ツールが初めて接続すると、ブラウザーウィンドウが開き、OAuth を使って FFmpeg Micro アカウントにサインインするよう求められます。承認すると、トークンがキャッシュされ、次回以降は求められません。

コピーする API キーも、設定する環境変数もありません。

認証

OAuth（推奨）

MCP サーバーは、PKCE と動的クライアント登録に対応した OAuth 2.1 をサポートしています。MCP クライアントが一連のフローを自動的に処理します。

1. クライアントが /.well-known/oauth-authorization-server 経由で OAuth エンドポイントを検出します
2. クライアントが動的に自身を登録します
3. サインインしてアクセスを承認するために、ブラウザーが開きます
4. トークンが交換されてキャッシュされます。以降の接続はすぐに完了します

上記の設定を headers ブロックや env ブロックなしで使用すると、これがデフォルトになります。

API キー（代替手段）

API キーを直接使用する場合（自動化や CI など）は、Bearer トークンとして渡せます。

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

API キーは ダッシュボード から取得できます。

stdio（ローカルインストール）

npx を使ってサーバーをローカルプロセスとして実行します。Node.js 22.14 以降が必要です。

{
  "mcpServers": {
    "ffmpeg-micro": {
      "command": "npx",
      "args": ["-y", "@ffmpeg-micro/mcp-server"],
      "env": {
        "FFMPEG_MICRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npx -y は実行するたびに最新バージョンを取得します。stdio サーバーに対応する MCP クライアントであれば、この設定で動作します。

対応ツール

HTTP 設定（OAuth）は、ストリーミング可能な HTTP トランスポートに対応するすべての MCP クライアントで使用できます。

• Claude Code（CLI）
• Claude Desktop
• Cursor
• Windsurf
• VS Code（GitHub Copilot MCP）

stdio 設定は、stdio トランスポートに対応するすべての MCP クライアントで使用できます。

プロンプトの例

接続したら、次のように尋ねることができます。

• 「この動画を 720p の MP4 にトランスコードして、完了したらダウンロード URL を教えてください。」
• 「この横長の動画を正方形にクロップしてください。」
• 「動画に『エピソード 12』というテキストをオーバーレイで追加してください。」
• 「今週失敗したジョブを一覧表示してください。」
• 「ジョブ b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3 をキャンセルしてください。」

開発

git clone https://github.com/ffmpeg-micro/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.sh

setup.sh は依存関係をインストールし、ビルドを実行して、git フックを設定します。

ローカルのビルドを MCP クライアントに指定すると、変更をすばやく試せます。

{
  "mcpServers": {
    "ffmpeg-micro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
      "env": { "FFMPEG_MICRO_API_KEY": "…" }
    }
  }
}

ツールのスキーマや応答を試すには、MCP Inspector を使うのが最も手軽です。

npx @modelcontextprotocol/inspector node dist/index.js

ローカル API ゲートウェイに接続して HTTP サーバーをローカルで実行するには、次のようにします。

FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serve

統合テストをローカルで実行する

FFMPEG_MICRO_API_KEY=your_key npm run test:integration

統合テストは、FFmpeg Micro の本番 API に接続します。読み取り専用のため、ジョブは作成されません。

アップロードツールをエンドツーエンドでスモークテストする

ユニットテストでは fetch をモックしているため、ツールの登録、Zod スキーマ、URL パスは検証できますが、通信データの形式がゲートウェイの実際の応答と一致するかは検証できません。2 つのスモークテストスクリプトでは、実際の API キーを使って、実際の MCP サーバーに対する request_upload_url → PUT → confirm_upload の一連のフローを実行します。順番に実行してください。まず stdio（最も早く状況を確認できます）、次にマージ前またはマージ後にデプロイ済みの HTTP サーバーで実行します。

# 1. stdio (local dist build) — spawns dist/index.js as a subprocess
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-upload-stdio.mjs <local-file>

# 2. HTTP (any deployed server — local `npm run serve`, Vercel preview, or prod)
FFMPEG_MICRO_API_KEY=your_key MCP_URL=https://mcp.ffmpeg-micro.com/ \
  node scripts/smoke-upload-http.mjs <local-file>

どちらのスクリプトもデフォルトで本番 API に接続し、課金対象の時間を消費します（stdio スクリプトではエンドツーエンドの確認のため、続けて transcribe_audio を実行します）。コストをわずかに抑えるには、15-second.mp3 のような小さなファイルを渡してください。

3 つ目のスクリプトでは、ブループリントツールをスモークテストします（resize-format で run_blueprint と get_blueprint_run を完了までポーリングし、その後 hook-variants で run_blueprint_and_wait を実行して複数出力を検証します）。FFmpeg レーンのブループリントのみを使用するため、プランのコンピューティング時間は消費しますが、トークンは消費しません。

npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjs

保護が有効な Vercel プレビューへのアクセス

Vercel のプレビューデプロイでは、デフォルトで Deployment Protection によるアクセス制限が適用されます。プレビュー URL に対して HTTP スモークスクリプトを実行するには、プロジェクトの Vercel 設定で Protection-Bypass-for-Automation トークンを生成し、VERCEL_BYPASS 経由で渡します。

FFMPEG_MICRO_API_KEY=your_key \
  MCP_URL=https://your-preview.vercel.app/ \
  VERCEL_BYPASS=your_bypass_token \
  node scripts/smoke-upload-http.mjs <local-file>

スクリプトは、すべてのリクエストでトークンを x-vercel-protection-bypass ヘッダーとして送信します。x-vercel-set-bypass-cookie: true は送信しません。この形式を使うと、POST で 307 の Cookie 設定リダイレクトが発生しますが、MCP SDK の StreamableHTTPClientTransport はこのリダイレクトを追従しないため、リクエストが失敗します。ヘッダーだけを使えば、リダイレクトを経由せずに直接 200 が返されます。

リリースプロセス

リリースはトラステッドパブリッシングを通じて npm に公開され、Ed25519 DNS TXT レコード（ffmpeg-micro.com）で認証されている com.ffmpeg-micro/mcp-server として MCP Registry に公開されます。対応する秘密鍵は、GitHub Actions シークレットの MCP_PRIVATE_KEY に保存されています。npm 側では OIDC トラステッドパブリッシングを使用しているため、npm トークンは保存されません。

リリースは Changesets によって自動化されています。コントリビューターがバージョンを手動で更新したり、コミットにタグを付けたり、公開コマンドを実行したりする必要はありません。PR に changeset を添付すれば、あとはリリースパイプラインが処理します。

コントリビューターの手順（すべての PR）

リリース対象のコードを変更するすべての PR に changeset を含める必要があります。CI チェックによって適用されます。

# While working on your PR:
npx changeset

CLI がバージョン更新の種類（major/minor/patch）と短い概要を尋ねます。.changeset/ の下に Markdown ファイルが作成されるので、そのファイルを PR と一緒にコミットしてください。

リリースを伴わない PR の例外措置（ドキュメント、CI、内部リファクタリング、動作に影響しないテストの変更）：

• PR に no-changeset ラベルを追加する、または
• npx changeset --empty を実行して「リリース不要」と明示する。

メンテナーの手順（リリースの実施）

リリースを手動で実施する必要はありません。パイプラインが処理します。

1. PR が main にマージされ、changeset ファイルが追加されます。
2. .github/workflows/release.yml が main へのプッシュごとに実行されます。未処理の changeset がある場合、アクションが作成者となり、chore(release): version packages PR を作成（または更新）します。この PR では次の処理を行います。
   • changeset version を実行し、未処理の changeset を反映する
   • package.json のバージョンを更新する
   • scripts/sync-server-version.mjs を使って server.json と src/version.ts を再同期する
   • CHANGELOG.md に項目を追加する
   • 結果を専用ブランチにコミットする
3. 出荷の準備ができたら、Version Packages PR をレビューしてマージします。複数の changeset がたまるまで待つこともできます。main にさらに PR がマージされると、この PR は自動で更新されます。
4. マージ時にリリースワークフローが再び実行されます。今度は未処理の changeset がないため、changesets/action がバージョン更新を検出し、次の処理を行います。
   • changeset publish を実行します。npm にそのバージョンがまだ公開されていない場合に限り、npm publish（プロベナンス証明付きの OIDC トラステッドパブリッシング）が実行されるため、main へのそれ以外のプッシュではこのステップを通過します。
   • GitHub Release と git タグを自動作成する
5. ワークフローの最後のステップで mcp-publisher をインストールし、DNS の秘密鍵で認証して、com.ffmpeg-micro/mcp-server として MCP Registry に公開します。

バージョン同期のチェック

.github/workflows/release.yml は、main へのプッシュごとにバージョンの一致をチェックします。package.json.version、server.json.version、server.json.packages[0].version に不一致があると、ビルドが明確なエラーとともに失敗します。src/version.ts の SERVER_VERSION は tests/version.test.ts によって検証されます。このテストでは、共有サーバービルダー（両方のエントリーポイントで使用される src/mcpServer.ts）とホストされた HTTP アプリから実際の initialize 応答を取得し、報告されるバージョンを確認します。通常は scripts/sync-server-version.mjs によってバージョンが同期されますが、同期処理を経なかった手動編集も、このチェックで検出できます。

確認

Version Packages PR がマージされ、ワークフローが成功したら：

npm view @ffmpeg-micro/mcp-server version
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=com.ffmpeg-micro/mcp-server" | jq '.servers[] | {v: .server.version, isLatest: ._meta."io.modelcontextprotocol.registry/official".isLatest}'

例：コントリビューター向けの手順

新しい delete_transcode ツールを追加するとします。PR の流れは次のとおりです。

git switch -c feat/delete-transcode
# ... make the code + test changes ...

npx changeset
# ? Which packages would you like to include? › @ffmpeg-micro/mcp-server
# ? Which type of change is this for @ffmpeg-micro/mcp-server? › minor
# ? Please enter a summary for this change › Add delete_transcode tool

git add .changeset/*.md src/ tests/
git commit -m "feat: add delete_transcode tool"
git push -u origin feat/delete-transcode
gh pr create

CI では次の 3 つのチェックが実行されます。

• test — 単体テスト
• check（Require changeset）— .changeset/*.md があることを確認
• Vercel — プレビューをデプロイ

マージ後、Version Packages PR が自動で作成されるか更新され、追加した項目が含まれます。リリースの準備ができたら、その PR をマージしてください。

ルール

• server.json、package.json、src/version.ts のバージョンフィールドを手動で編集しないでください。 これらは Changesets が管理します。scripts/sync-server-version.mjs が package.json の内容を server.json と src/version.ts に反映します。これらに不整合があると、CI のドリフトチェックによりリリースが失敗します。
• リリースに対して手動で git tag を実行しないでください。 changesets/action が公開処理の一環としてタグと GitHub Release を作成します。手動で作成したタグは新しいワークフローでは検出されません。
• .changeset/config.json または .changeset/README.md を変更して、Require-changeset チェックを回避しないでください。 これらは変更としてカウントされません。npx changeset、no-changeset ラベル、または npx changeset --empty を使用してください。

リリース関連のファイル

• package.json — バージョンの信頼できる唯一の情報源です。MCP Registry による npm パッケージの検証に必要な mcpName も含まれます。changeset version によって更新されます。
• server.json — MCP Registry のメタデータです。バージョンフィールドは package.json から自動的に同期されます。
• .changeset/config.json — Changesets の設定です（パブリックアクセス、GitHub 対応の変更履歴フォーマッター）。
• .changeset/*.md — 次回の changeset version の実行時に反映される、未処理のリリースノートです。
• scripts/sync-server-version.mjs — package.json のバージョンを server.json と src/version.ts（サーバーが initialize で報告するバージョン）に反映します。
• .github/workflows/release.yml — 公開パイプラインです（changesets/action と MCP Registry のステップ）。
• .github/workflows/require-changeset.yml — PR に変更セットが含まれていることを必須にします。

トラブルシューティング

• PR で Require changeset チェックに失敗する場合 — npx changeset を実行し、生成されたファイルをコミットしてください。ドキュメントのみ、または CI のみを変更する PR では、no-changeset ラベルを追加するか、npx changeset --empty を実行してください。
• CI がバージョン同期ガードのステップで失敗する場合 — server.json が手動で編集されています。ローカルで node scripts/sync-server-version.mjs を実行し、コミットしてプッシュしてください。このガードは package.json.version、server.json.version、server.json.packages[0].version を比較します。代わりに tests/version.test.ts が失敗する場合は、src/version.ts にずれがあります。同じ node scripts/sync-server-version.mjs を実行すれば修正できます。
• 機能追加の PR がマージされた後、changesets/action が Version Packages PR を作成しなかった場合 — PR の .changeset/*.md ファイルに実際に内容があったか（バージョンアップの種類と概要を含む空でないフロントマター）を確認してください。空の変更セットは「リリース不要」を示すため、意図的に無視されます。
• mcp-publisher publish が「package not found」エラーで失敗する場合 — npm で新しいバージョンの反映がまだ完了していません。リリースワークフローの Determine if MCP Registry publish is needed ステップは、最大約 50 秒間 npm view を再試行し、バージョンがまだ公開されていなければ待機時間を延ばします。その場合、レジストリへの公開は次回の main へのプッシュまで延期され、ずれは自動的に修正されます。手動実行でこの問題が発生した場合は、30 秒待ってから再公開してください。
• MCP Registry のバージョンが npm より 1 つ古いままの場合 — Determine if MCP Registry publish is needed ステップがスキップされたか、needed=false を返しています。main に任意のコミットをプッシュして再実行してください。このゲートは package.json ↔ npm ↔ レジストリを比較し、自動的に追いつかせます。スキップが続く場合は、ステップのログ出力で各ソースが報告したバージョンを確認してください。
• mcp-publisher publish が「mcpName mismatch」の検証エラーで失敗する場合 — package.json の mcpName は server.json の name と一致している必要があります（どちらも com.ffmpeg-micro/mcp-server である必要があります）。
• mcp-publisher login dns が「public key mismatch」エラーで失敗する場合 — MCP_PRIVATE_KEY シークレットが ffmpeg-micro.com の TXT レコードと一致しなくなっています。ローカルでキーペアを再生成し、TXT レコードと GitHub シークレットの両方を更新してください。

ライセンス

MIT — LICENSE を参照してください。