AppsGolem YouTube Cutter

appsgolem-mcp (Node / TypeScript)

AppsGolem YouTube カッター API 用の MCP サーバーです。AI エージェント（Claude Desktop、Claude Code、Cursor、…）を使って、YouTube 動画からクリップを切り出せます。Web カッターが対応するあらゆる形式で切り出し、直接ダウンロードできる URL を取得できます。REST ロジックは、依存関係を最小限に抑えた小さなクライアント（src/client.ts）にあり、src/server.ts はその上に構築された薄い MCP ツールレイヤーです。

API キーを取得 → appsgolem.com/agents — 登録してプリペイドクレジットを追加し、キー（ag_live_…）を生成してください。このページには、Claude Code、Codex、Cursor、およびあらゆる MCP クライアント向けのコピー＆ペーストで使えるセットアップ手順と、プロンプトの活用例も掲載されています。

要件

• Node.js >= 18（グローバルの fetch を使用します）。
• AppsGolem API キー（ag_live_…）— appsgolem.com/agents で取得できます（登録 → クレジットを追加 → ダッシュボードでキーを生成）。クレジットはプリペイド方式です。パックまたはサブスクリプションを購入してください。自動更新は不要です。

インストール / 接続（手動インストール不要）

npx が必要に応じてサーバーを取得して実行するため、グローバルにインストールする必要はありません。

Claude Desktop / Cursor — クライアントの MCP 設定（例： claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "appsgolem": {
      "command": "npx",
      "args": ["-y", "appsgolem-mcp"],
      "env": { "APPSGOLEM_API_KEY": "ag_live_…" }
    }
  }
}

Claude Code — 次のコマンドを実行します。

claude mcp add appsgolem -e APPSGOLEM_API_KEY=ag_live_… -- npx -y appsgolem-mcp

サーバーは、これらのクライアントが使用するトランスポートである stdio 経由で MCP を通信します。起動時に APPSGOLEM_API_KEY が設定されていなくても致命的なエラーにはなりません。サーバーは起動してツールを公開し、各呼び出しではキーを設定するよう案内する、明確な config_error を返します。

設定

環境変数	必須	デフォルト	備考
APPSGOLEM_API_KEY	はい	—	ag_live_… キーです。
APPSGOLEM_API_BASE	いいえ	https://appsgolem.com	セルフホスト / 開発用の上書き設定です。

料金

生成したクリップ 1 本につき 1 クレジットです。2160p（4K）ではクリップ 1 本につき 4 クレジットです。ただし、audio_only は 1 クレジットのままです。ソースが 2 時間を超える場合、ジョブごとに一度だけ +1 クレジットが加算されます。ただし、長さが判明している場合に限ります（プローブで長さを特定できない場合、この追加料金は発生しません）。N 本のクリップをバッチ処理または結合する場合、クリップごとの料金は N です。失敗した切り出しに料金は発生しません。

---

ツール

サーバーは3 つのツールを公開します。MCP の入力スキーマ検証を通過した呼び出しは、成功時には API 独自の JSON を、ハンドラーまたは API のエラー時には { "error": … } を含む構造化された結果を返し、プロトコルレベルのエラーは発生させません。そのため、エージェントは常に利用可能なオブジェクトを受け取れます。（無効なツールの引数はハンドラーの実行前に MCP SDK によって拒否され、テキストのみの isError 結果として返されます。）

1. cut_youtube_video

YouTube 動画からクリップ（または複数のクリップ）を切り出します。デフォルトでは、クリップの生成が完了するまで待機し、ステータスを返します（ダウンロードトークンの準備ができると download_url が含まれます）。wait: false を設定すると、送信後すぐに現在のジョブを返します（通常、送信後の状態は queued です）。

パラメーター

名前	型	デフォルト	備考
url	文字列	—	必須。 YouTube の視聴用／共有用／youtu.be URL。プレイリストは拒否されます。
start	文字列	—	クリップの開始位置："SS"、"MM:SS"、または "HH:MM:SS"（≤ 300 h）。clips を使用する場合は省略します。
end	文字列	—	クリップの終了位置。同じ形式（≤ 300 h）。clips を使用する場合は省略します。
resolution	文字列	1080p	144p · 240p · 360p · 480p · 720p · 1080p · 1440p · 2160p（4K。切り出し合計は ≤ 60 min）。
mode	文字列	video	video · audio_only · both · nosound · short · gif · frames（下記のモードを参照）。
audio_format	文字列	—	audio_only の出力形式：mp3 · m4a · wav · flac（サーバーのデフォルトは mp3）。both では常に MP3 が生成されます。
bitrate	文字列	—	非可逆音声のビットレート 320 · 256 · 192 · 128（デフォルトは 320）：audio_only の MP3/M4A、both の MP3 に適用されます。WAV/FLAC では無視されます。
fast	boolean	false	ストリームコピー（約 10 倍高速、キーフレームに合わせて切り出し）。video / nosound / both のみ。1× 以外の speed とは同時に指定できません。両方を設定すると、fast が優先され、speed は 1.0 に強制されます。
speed	number	1.0	再生速度 0.5 · 1 · 1.25 · 1.5 · 2。video / nosound / both / audio_only に適用されます。
interval_ms	integer	2000	frames のサンプリング間隔：100 · 500 · 1000 · 2000 · 5000 · 10000（シート形式ではない抽出は、すべてのクリップ合計で 1,800 JPG までに制限されます）。
burn_ts	boolean	false	frames：各 JPG にソースのタイムスタンプを焼き込みます。
sheet	boolean	false	frames：コンタクトシート形式の JPG を 1 枚返します（2～80 フレーム、クリップは 1 つ）。有効にすると burn_ts は無効になります。
clips	array	—	start / end の代わりに指定する { start, end } 範囲の配列（1～10 個）。空の配列は拒否されます。
stitch	boolean	false	clips が 2 個以上の場合、それらを 1 つのファイルに結合します（それ以外の場合はクリップを ZIP にまとめます）。クリップが 1 つの場合は無視されます。video / audio_only / both / short / nosound に適用されます。
idempotency_key	文字列	—	安定したキー（≤ 200 chars）。リトライしたリクエストで同じジョブを再利用するために使用します（Idempotency-Key ヘッダーとして送信）。
wait	boolean	true	timeout_seconds のポーリング期限まで準備ができるのを待ちます。
timeout_seconds	integer	300	ポーリングの期限（秒、デフォルトは 300）。期限が適用されるのはポーリングのみです。初回送信と処理中のステータスリクエスト 1 回（それぞれリクエストタイムアウトは最大 30 秒）により、合計の経過時間はさらに長くなる場合があります。

戻り値（wait: true、デフォルト） — 生成されたジョブのステータスです。ダウンロードトークンが利用可能になると download_url が含まれます。まだ利用できない場合は、再度ポーリングしてください。

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "produced",
  "credits_reserved": 1,
  "created_at": "2026-08-22T12:00:00+00:00",
  "download_url": "https://appsgolem.com/v1/download/…/clip.mp4"
}

戻り値（wait: false） — 現在の状態（送信後は通常 queued）のジョブをすぐに返します。download_url はまだ含まれません。id を使って get_cut_status をポーリングするか、poll_url を取得してください。

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "queued",
  "credits_reserved": 1,
  "poll_url": "/v1/cuts/e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
}

クリップの準備ができる前に待機がタイムアウトした場合、結果には "still_processing": true とジョブの id が含まれます。その id を使って get_cut_status をポーリングしてください。ジョブが最終的に失敗した場合、結果は { "error": "cut_failed", "state": "failed" | "refunded", "id": … } となり、クレジットは消費されません。

2. get_cut_status

ID でカットジョブを確認します。cut_youtube_video(wait=false) で開始したジョブ、またはタイムアウトしたジョブの状態をポーリングする際に使用します。

名前	型	備考
job_id	string	必須。 cut_youtube_video が返すジョブ ID（UUID）です。

戻り値 — ジョブの状態です。生成・配信されると、ダウンロードトークンが利用可能な場合は download_url も含まれます（利用できない場合は再度ポーリングしてください）。

{ "id": "e48db1a2-…", "state": "queued", "credits_reserved": 1, "created_at": "…" }

状態は accepted → queued → produced → delivered の順に進みます。エラーが発生した場合は failed → refunded に進みます。

3. get_account_balance

API アカウントで利用可能なクレジット残高と現在の時間あたりの上限を返します。パラメーターはありません。

戻り値

{ "balance": 412, "hourly_cap": 60 }

---

モード

mode	出力	主なオプション
video	透かしのない動画ファイル — 通常は MP4 です。fast を指定すると、ソースのコンテナーが保持されます（高解像度では WebM など）。	resolution、fast、speed
audio_only	mp3 / m4a / wav / flac	audio_format、bitrate、speed
both	動画と MP3 をまとめた zip ファイルです（fast を指定すると、動画のソースコンテナーが保持される場合があります）。	bitrate、fast、speed
nosound	音声トラックのない動画 — 通常は MP4 です。fast を指定すると、ソースのコンテナーが保持されます。	resolution、fast、speed
short	縦向きの 9:16 動画 — 適用可能な場合は AI によるスマートクロップを行い、それ以外の場合はレターボックスとぼかしによるフォールバックを使用します。正確なアスペクト比はソースによって異なります（Shorts / Reels / TikTok）。	resolution
gif	アニメーション GIF（5 分以下、複数クリップには非対応）	resolution
frames	JPG の静止画	interval_ms、burn_ts、sheet

---

プロンプトの例

エージェントがリクエストからパラメーターを選択するため、自然言語で指示できます。

• 「https://youtu.be/dQw4w9WgXcQ の 0:30 から 1:15 までを 1080p でカットしてください。」 → cut_youtube_video(url, start="0:30", end="1:15")
• 「その動画の 2:00 から 5:00 までの音声を mp3 で取得してください。」 → mode="audio_only", audio_format="mp3"
• 「10:00〜10:45 のハイライトを縦向きのショート動画にしてください。」 → mode="short", start="10:00", end="10:45"
• 「0:05〜0:12 を GIF にしてください。」 → mode="gif"
• 「1:00 から 2:00 まで、5 秒ごとのフレームでコンタクトシートを作成してください。」 → mode="frames", interval_ms=5000, sheet=true
• 「0:10〜0:20 と 1:00〜1:10 を 1 つのクリップにつなげてください。」 → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true
• 「0:00〜0:30 をストリームコピーで高速カットしてください。」 → fast=true
• 「API クレジットの残りはいくつですか？」 → get_account_balance()

---

結果とエラーの形式

ハンドラーから返されるすべての結果はプレーンオブジェクトです（MCP の引数検証エラーは例外です。上記の「ツール」の注記を参照してください）。失敗時も、オブジェクトに error コードが含まれるだけで、ツール呼び出し自体は成功します。

error	発生条件
config_error	APPSGOLEM_API_KEY が設定されていません。
invalid_api_key	キーが拒否されました（401）。
invalid_job_id	job_id が UUID ではありません。
not_found	このアカウントに該当するジョブがありません（404）。
cut_failed	ジョブが failed／refunded に到達しました（請求は発生しません）。
network_error	接続／トランスポートの失敗、またはリクエストのタイムアウトです。
bad_request	設定された API のベース／パスを URL として構築できませんでした。
http_error	JSON 本文が { error: … } オブジェクトではない ≥400 のレスポンスです（status を含みます）。
bad_response	成功レスポンスの本文が JSON オブジェクトではありません（配列／スカラー／null）。または、wait: true の場合、カットの送信結果に使用可能なジョブの id が含まれていません。

API レベルのエラー（検証エラー 400、402 insufficient_credits、 404 not_found、409 idempotency_conflict／duplicate_in_flight、 429 rate_limited、503 rate_limiter_unavailable／database_busy）は、 API 独自のエラー本文に status フィールドを加えて返されます。429 にはさらに retry_after（Retry-After に基づく秒数）と reason （submission_cap・request_rate・poll_rate）が含まれるため、エージェントは どの制限に達したかを確認し、適切にバックオフできます。503 は通常一時的なため 短時間待ってから再試行してください。ただし、503 が継続する場合はサーバー側の 問題として報告し、無期限に再試行しないでください。

通常の使用では、ステータスのポーリングにレート制限はありません。ジョブの進捗確認が、 1 時間あたりの送信上限にカウントされることはありません。get_cut_status を自分で スロットルする必要はありません。cut_youtube_video(wait=true) がポーリングの間隔を調整し、 サーバーの poll_after の間隔と Retry-After を尊重するため、長時間かかるジョブも 1 回のツール呼び出しで処理できます。

生成されたダウンロードリンクには、一定期間の有効期限があります（appsgolem.com では デフォルトで約 72 時間。デプロイごとに設定可能です）。期限内にファイルを取得してください。

相対 download_url（API がパスを返す場合）は、結果が同一オリジンにとどまる場合にのみ、 設定された API ベースを基準に完全な URL へ解決されます。API のオリジン外に解決される download_url（別のホストを指す絶対 URL、またはオリジン外へ抜ける相対パス）は、 安全のため破棄されます。フィールドが削除され、結果に download_url_dropped: true が含まれるため、単にジョブがまだ生成されていない状態と区別できます。 cut_youtube_video が完了を待機しているとき（デフォルトでは wait=true）にオリジン外の リンクが返された場合は、不正な URL を返す代わりに download_url_unsafe エラーが 返されます。

---

開発

npm install
npm run build      # tsc -> dist/
npm test           # builds, then runs node --test (no network)
npm start          # run the stdio server locally (key needed for calls, not startup)

公開

（このディレクトリで）npm publish を実行すると、誰でも npx appsgolem-mcp を 使用できるようになります。prepare スクリプトは、インストール／公開時に dist/ を 自動的にビルドします。