YouTube Transcripts

YouTube Transcript Agent

YouTube の動画、再生リスト、またはチャンネルを、エージェント向けの文字起こしコンテキストに変換します。

このパッケージには、次のものが含まれています。

• 文字起こし、チャンネルジョブ、再生リストジョブ、ポーリング、ZIP ダウンロード用の CLI ytx
• コーディングエージェントとデスクトップアシスタント向けのローカル stdio MCP サーバー
• ホスト型 /mcp エンドポイントと Developer API の利用に関するドキュメント

インストール

インストールせずに実行するには：

npx youtube-transcript-agent --help

または、グローバルにインストールします。

npm install -g youtube-transcript-agent
ytx --help

認証

CLI は次の順序で認証情報を読み込みます。

1. YOUTUBE_TRANSCRIPT_API_KEY
2. ytx auth set-key で作成したローカル設定

API キーを設定します。

npx youtube-transcript-agent auth set-key <api_key>

または、環境変数を使用します。

export YOUTUBE_TRANSCRIPT_API_KEY=<api_key>

PowerShell：

$env:YOUTUBE_TRANSCRIPT_API_KEY="<api_key>"

CLI の使い方

アカウントのクレジットを取得します。

npx youtube-transcript-agent credits

文字起こしを 1 件取得します。

npx youtube-transcript-agent transcript FOp280ZAxhg --timestamps

チャンネルの文字起こしをダウンロードします。

npx youtube-transcript-agent channel download "@mkbhd" --max 25 --wait --output channel.zip

再生リストの文字起こしをダウンロードします。

npx youtube-transcript-agent playlist download <playlist_url_or_id> --max 25 --wait --output playlist.zip

ジョブをポーリングします。

npx youtube-transcript-agent jobs status <job_id>

完了したジョブをダウンロードします。

npx youtube-transcript-agent jobs download <job_id> --output transcripts.zip

ローカル MCP

ローカル stdio MCP サーバーを起動します。

npx youtube-transcript-agent mcp

このコマンドは、stdin で JSON-RPC メッセージを待ち受けます。エージェントクライアントは、次のコマンドで起動してください。

Command: npx
Args: youtube-transcript-agent mcp
Env:
  YOUTUBE_TRANSCRIPT_API_KEY=<api_key>

利用可能な MCP ツール：

• get_transcript
• get_channel_info
• list_channel_videos
• start_channel_job
• start_playlist_job
• get_job_status
• get_download_url

手動でのスモークテスト：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx youtube-transcript-agent mcp

ホスト型 MCP

ホスト型 MCP を有効にして API サーバーをデプロイしている場合：

Endpoint: https://api.youtubetranscripts.fbetteo.com/mcp
Auth: Authorization: Bearer <api_key>

ツールを一覧表示します。

curl -X POST "https://api.youtubetranscripts.fbetteo.com/mcp" \
  -H "Content-Type: application/json" \
  --data-raw '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

ツールを呼び出します。

curl -X POST "https://api.youtubetranscripts.fbetteo.com/mcp" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  --data-raw '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_transcript","arguments":{"video_url":"FOp280ZAxhg"}}}'

エージェントスキル

このリポジトリには、インストール可能なスキルテンプレートが含まれています。

agent-skill/skill.md

配布するには、そのファイルを別の公開スキルリポジトリのルートにある skill.md として公開してください。

トラブルシューティング

API ホストの詳細な上書き

ほとんどのユーザーは API URL を設定する必要はありません。このパッケージでは、デフォルトでホスト型の本番 API を使用します。

カスタムのベース URL は、ローカル開発、ステージング、セルフホスト型のデプロイ、またはデバッグの場合にのみ設定してください。

export YOUTUBE_TRANSCRIPT_API_BASE_URL=http://127.0.0.1:8000

または、ローカル CLI 設定に保存します。

npx youtube-transcript-agent auth set-key <api_key> --base-url http://127.0.0.1:8000

トラブルシューティング

fetch failed が表示され、API ログに何も記録されていない場合、CLI は API ホストに到達できていません。次の点を確認してください。

echo "$YOUTUBE_TRANSCRIPT_API_BASE_URL"
echo "$API_BASE_URL"
cat ~/.youtube-transcript-agent/config.json 2>/dev/null

CLI のベース URL は、次の優先順位で使用されます。

1. YOUTUBE_TRANSCRIPT_API_BASE_URL
2. API_BASE_URL
3. 保存済みのローカル設定
4. パッケージのデフォルト値

Windows PowerShell では、チャンネルハンドルを引用符で囲んでください。

node cli/dist/cli.js channel download "@mkbhd" --max 2 --wait

PowerShell では curl が Invoke-WebRequest のエイリアスになっています。curl.exe または Invoke-RestMethod を使用してください。