@ffmpeg-micro/mcp-server

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

機能

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

ブループリント

ブループリントは POST /v1/blueprints/{slug}/runs の背後にある事前構築済みワークフローです。各ブループリントの入力フィールドはツールの説明に記載されています。注意点：

• ほとんどのブループリントはFFmpegレーンで実行され、プランのコンピュート時間を消費します（トークンは消費しません）。生成系ブループリント（product-ad）はトークンを消費します。402 insufficient_tokens レスポンスは、アカウントにトークンパックが必要であることを意味します（ダッシュボード）。

• caption-video は awaiting_review で一時停止し、文字起こし（srt_text）を返すため、エージェントはレンダリング前にレビュー・編集できます。continue_blueprint_run で再開します。

• 複数出力のブループリント（listing-kit、hook-variants）は outputs 配列として {label, url} を返します。存在する場合は output_url よりもこちらを優先してください。

• 出力URLは有効期限10分で署名されています。新しいリンクを取得するには実行を再取得してください。

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

request_upload_url + confirm_upload のペアにより、MCPホストは生のAPIキーや gs:// URLを扱うことなく、ローカルファイルをFFmpeg Microのストレージバケットにアップロードできます：

1. ホストが {filename, contentType, fileSize} を指定して request_upload_url を呼び出します → 有効期限の短い署名付きHTTPS URLを受け取ります。

2. ホストは同じ Content-Type でファイルのバイト列をそのURLにPUTします。

3. ホストが {filename: <ステップ1で受け取ったストレージファイル名>, fileSize} を指定して confirm_upload を呼び出します → 最終的な gs://... の fileUrl を受け取ります。

4. ホストはその fileUrl を transcribe_audio / transcode_video / transcode_and_wait に渡します。

Related MCP server: Rendi MCP Server

クイックスタート

これをプロジェクトの .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/javidjamae/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つ目のスクリプトはブループリントツールのスモークテストを行います（run_blueprint + get_blueprint_run を resize-format で完了までポーリングし、その後 run_blueprint_and_wait を hook-variants で実行して複数出力を検証します）。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リダイレクトをトリガーし、MCP SDKの StreamableHTTPClientTransport がリダイレクトに追従しないため、リクエストが失敗します。ヘッダー単独では、リダイレクトによる追加の往復なしで直接200が返ります。

リリースプロセス

リリースはトラステッドパブリッシング経由でnpmに公開され、com.ffmpeg-micro/mcp-server としてMCPレジストリにも公開されます。認証は ffmpeg-micro.com 上のEd25519 DNS TXTレコードを介して行われます。対応する秘密鍵は MCP_PRIVATE_KEY GitHub Actionsシークレットに保存されています。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. changesetファイルを添付したPRが main にマージされます。

2. .github/workflows/release.yml が main へのプッシュのたびに実行されます。保留中のchangesetが存在する場合、アクションによって作成（または更新）された chore(release): version packages PRが開かれます。そのPRは：

   • 保留中のchangesetを消費するために changeset version を実行

   • package.json をバンプ

   • scripts/sync-server-version.mjs で server.json を再同期

   • CHANGELOG.md にエントリを追記

   • 結果を自身のブランチにコミット

3. 出荷する準備ができたらVersion Packages PRをレビューしてマージします。複数のchangesetを蓄積してからマージすることもできます。main にさらにマージされるたびにPRは自動更新されます。

4. マージ時にリリースワークフローが再度実行されます。今回は保留中のchangesetがないため、changesets/action がバージョンバンプを検出して：

   • npm publish（OIDCトラステッドパブリッシング、来歴証明付き）

   • GitHub Releaseとgitタグを自動的に作成

5. ワークフローの最終ステップで mcp-publisher をインストールし、DNS秘密鍵で認証して、com.ffmpeg-micro/mcp-server としてMCPレジストリに公開します。

バージョン同期ガード

.github/workflows/release.yml は main へのプッシュのたびにバージョン一致チェックを実行します。package.json.version、server.json.version、server.json.packages[0].version がずれた場合、ビルドは明確に失敗します。通常は 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 は自動的に開かれるか、自身を更新してあなたのエントリーを含めます。リリースの準備ができたら、それをマージしてください。

ルール

• server.json または package.json のバージョンフィールドを手動で編集しないでください。 Changesets が両方を管理します。scripts/sync-server-version.mjs が package.json を server.json にミラーリングします。CI のドリフトガードは、両者が乖離するとリリースを失敗させます。

• リリースに手動で git tag を付けないでください。 changesets/action は publish の一部としてタグと GitHub Release を作成します。手動のタグは新しいワークフローでは認識されません。

• Require-changeset チェックを迂回しないでください。 .changeset/config.json や .changeset/README.md への変更をコミットしても、それらはカウントされません。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 にミラーリングします。

• .github/workflows/release.yml — 公開パイプライン（changesets/action + MCP Registry ステップ）。

• .github/workflows/require-changeset.yml — PR に changeset が存在することを強制します。

トラブルシューティング

• 自分の 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 を比較します。

• 機能 PR のマージ後に changesets/action が Version Packages PR を開かなかった — PR の .changeset/*.md ファイルに実際にコンテンツ（バンプタイプとサマリーを含む空でない front matter）があったか確認してください。空の changeset は「リリース不要」を示し、意図的に無視されます。

• mcp-publisher publish が "package not found" で失敗する — npm が新しいバージョンの伝播をまだ完了していません。リリースワークフローの Determine if MCP Registry publish is needed ステップは npm view を最大約 50 秒間再試行し、それでもバージョンが公開されていない場合はバックオフして、レジストリへの公開を次の 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 を参照してください。