YouTube Transcripts, Search & Summaries

YouTube Transcripts MCP サーバー

ホステッド版（セットアップ不要）： apify.com/parallelstudio/youtube-transcripts-mcp。Apify トークンを使って、任意の MCP クライアントを https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp に接続し、呼び出しごとに料金をお支払いください。このリポジトリはオープンソースのコードです。npm install && npm run build && node dist/index.js（stdio）を実行して、ローカルで動かすこともできます。

AI エージェントに YouTube の文字起こし、検索、チャプター、要約を提供します。この MCP サーバーは、公開されているあらゆる YouTube 動画の字幕を、そのメタデータとともに取得します。字幕はプレーンテキスト、タイムスタンプ付きのセグメント、SRT 形式で取得できます。また、YouTube の検索やチャプターの取得に加え、各ポイントから元の該当箇所にリンクする、構造化された抽出型要約を作成します。

Claude Desktop、Claude Code、Cursor、VS Code、Windsurf をはじめ、Streamable HTTP 経由の MCP に対応するあらゆるクライアントで動作します。YouTube API キーも Google アカウントも必要ありません。サーバー上では LLM を実行しないため、他者のトークン料金を負担する必要もありません。

できること

• 調査を効率化します。「2 時間のポッドキャストを要約して、タイムスタンプ付きの重要なポイントを 10 個教えてください。」
• **動画に関する質問に答えます。**文字起こしを読み込み、エージェントに正確な箇所を引用・参照させます。
• **長い動画をナビゲートします。**投稿者が設定したチャプターを取得します。動画にチャプターがない場合は、文字起こしから生成したトピック別セグメントを取得します。
• **情報源を見つけます。**アップロード日、長さ、並べ替え順、「字幕あり」などのフィルターを使って YouTube を検索し、有力な検索結果の文字起こしを取得します。
• **コンテンツを再活用します。**任意の字幕言語または YouTube の機械翻訳を使って、SRT 字幕をエクスポートしたり、番組のメモを作成したり、トークをもとにブログ記事の下書きを作成したりできます。

ツール

ツール	機能	主なパラメーター
get_transcript	タイトル、チャンネル、長さ、再生回数、公開日、カテゴリ、利用可能な字幕言語、返された字幕トラックが自動生成かどうかなど、文字起こしとメタデータを返します。出力形式は、プレーンテキスト、[m:ss] 形式のタイムスタンプ付き段落、{start, duration, text} セグメント、または SRT です。YouTube の機械翻訳も利用できます。	video、languages（優先順位リスト、デフォルトは ["en"]）、format（text | segments | srt）、include_timestamps、translate_to、allow_auto_generated、fallback_to_any_language、max_chars
search_videos	ウェブサイトと同じ InnerTube 検索 API を使って YouTube を検索します。ID、タイトル、チャンネル、長さ、再生回数、相対的な公開時期、説明の抜粋、サムネイル、ライブ配信フラグ、バッジを返します。limit に達するまで、追加ページを自動で取得します。	query、limit（1～50）、upload_date（hour～year）、duration（short は 4 分未満、medium は 4～20 分、long は 20 分超）、sort_by、features（例：subtitles、live、hd、creative_commons）、hl、gl
get_video_chapters	開始・終了時刻と詳細リンク付きでチャプターを返します。説明欄にある投稿者のチャプターまたは YouTube のチャプターマーカーを使用します。いずれもない場合は、文字起こしからトピック別セグメントを導き出し、それぞれに特徴的なキーワードと代表的な文を使ったタイトルを付けます。	video、source（auto | description | transcript）、languages、target_chapters
summarize_transcript	LLM を使わず、構造化された抽出型要約を作成します。TL;DR、重複を除いた重要なポイント、キーワードとキーフレーズ、チャプターごとの箇条書き、注目すべき引用が含まれます。各項目にはタイムスタンプと …&t=123s 形式のリンクが付きます。	video、max_points（1～30、デフォルトは 8）、languages、bullets_per_chapter、max_quotes、keyword_limit

video には、11 文字の ID（dQw4w9WgXcQ）または任意の YouTube URL を指定できます。対応形式は、watch?v=、youtu.be/、/shorts/、/embed/、/live/、m. および music. ホスト、youtube-nocookie.com です。

すべてのツールは読み取り専用です。

エラーコード

エラーは MCP ツールエラー（isError: true）として返されます。テキストは Error (<CODE>): … で始まり、structuredContent.error には { code, message, retryable, details } が含まれます。そのため、エージェントはメッセージを解析する代わりにコードに応じて対応できます。

コード	意味
INVALID_VIDEO_ID / INVALID_INPUT	動画 ID／URL、またはその他の引数が無効です
VIDEO_UNAVAILABLE	削除済み、存在したことがない、または ID が間違っています
VIDEO_PRIVATE	動画は非公開です
AGE_RESTRICTED	YouTube ではサインイン済みアカウントが必要です（年齢制限）
VIDEO_UNPLAYABLE	メンバー限定、地域制限、配信予定のライブ配信などです（details.reason に YouTube のテキストが含まれます）
TRANSCRIPTS_DISABLED	動画に字幕がありません
NO_TRANSCRIPT_FOUND	要求した言語が一つも存在せず、fallback_to_any_language が false です。details.available には存在する字幕トラックが一覧表示されます
TRANSLATION_UNAVAILABLE	YouTube はこのトラックを translate_to に指定された言語に翻訳できません
NO_CHAPTERS	source: "description" が要求されましたが、説明にチャプター一覧がありません
REQUEST_BLOCKED	サーバーがプロキシセッションを切り替えた後も、YouTube にリクエストをブロックされました（HTTP 429、reCAPTCHA、または「ボットではないことを確認してください」）。retryable: true
PO_TOKEN_REQUIRED / EMPTY_TRANSCRIPT	YouTube が PO トークンを必要とする字幕 URL を返したか、字幕ファイルが空です
UPSTREAM_ERROR / INTERNAL_ERROR	タイムアウト、5xx レスポンス、または予期しないレスポンス形式です

料金

この Actor ではイベントごとの従量課金が適用されます。ツールイベントは、ツール呼び出しが成功した場合にのみ課金されます。検証エラー、動画が非公開または字幕がない場合、YouTube にリクエストをブロックされた場合など、失敗した呼び出しはツールイベントとして課金されません。Apify では、サーバーインスタンスが起動するたびに、標準の Actor 起動イベント（メモリ 1 GB あたり $0.00005、最低 1 イベント）も課金されます。デフォルトのスタンバイメモリ 512 MB では、起動 1 回あたり $0.00005 です。1 つの実行中インスタンスは、アイドル状態になるまでに多数の呼び出しを処理します。この Actor の料金タブが、現在の料金の正式な一覧です。

イベント	料金	課金されるタイミング	回数
transcript	$0.005	get_transcript の呼び出しが成功するたび	動画の長さや形式にかかわらず、呼び出し 1 回につき 1 回
search	$0.003	search_videos の呼び出しが成功するたび	呼び出し 1 回につき 1 回（最大 50 件の結果。自動取得された追加ページを含みます）
chapters	$0.008	get_video_chapters の呼び出しが成功するたび	呼び出し 1 回につき 1 回。説明から取得するか、字幕から生成します
summary	$0.015	summarize_transcript の呼び出しが成功するたび	呼び出し 1 回につき 1 回。内部で取得された字幕は、transcript として別途課金されません

検索結果が 0 件でも呼び出しは成功とみなされ、search イベント 1 回分が課金されます。

MCP クライアントを接続する

エンドポイント（Streamable HTTP）：

https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp

Apify API トークンを Authorization: Bearer <APIFY_TOKEN> として送信し、認証します。

Cursor（~/.cursor/mcp.json または .cursor/mcp.json）

{
  "mcpServers": {
    "youtube-transcripts": {
      "url": "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Windsurf（~/.codeium/windsurf/mcp_config.json）

{
  "mcpServers": {
    "youtube-transcripts": {
      "serverUrl": "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

Claude Desktop の設定ファイルはローカル（stdio）サーバーのみを起動するため、mcp-remote（Node.js が必要）を使ってホストされたエンドポイントに接続します。同じブロックは、stdio のみをサポートする他のクライアントでも使用できます。

{
  "mcpServers": {
    "youtube-transcripts": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
        "--header", "Authorization: Bearer ${APIFY_TOKEN}"
      ],
      "env": { "APIFY_TOKEN": "<APIFY_TOKEN>" }
    }
  }
}

ヘッダーを送信できないクライアント

Apify はトークンを token クエリパラメーターとして指定する方法もサポートしているため、URL のみを受け付けるクライアントでは次のように指定できます。

https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp?token=<APIFY_TOKEN>

クライアントが対応している場合は、Authorization ヘッダーを使用してください。URL 内のトークンはログに残る可能性があります。スコープを限定した Apify トークンを使えば、漏えいした場合の被害を抑えられます。

Claude Code

claude mcp add --transport http youtube-transcripts \
  https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp \
  --header "Authorization: Bearer $APIFY_TOKEN"

VS Code（.vscode/mcp.json）

{
  "servers": {
    "youtube-transcripts": {
      "type": "http",
      "url": "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
      "headers": { "Authorization": "Bearer ${input:apifyToken}" }
    }
  },
  "inputs": [{ "id": "apifyToken", "type": "promptString", "description": "Apify API token", "password": true }]
}

プロンプトの例

• 「https://youtu.be/aircAruvnKk のトランスクリプトを取得して、タイムスタンプを示しながら勾配降下法について説明してください。」
• 「過去1年間のRustの非同期処理に関する講演を検索し、20分を超えて字幕があるものの中から、上位3件を要約してください。」
• 「この3時間のライブ配信のチャプターを教えてください。チャプターがない場合は、トピックごとに分割してください。」
• 「この動画のドイツ語字幕をSRT形式で書き出してください。ドイツ語の字幕トラックがない場合は翻訳してください。」

出力例

以下の抜粋は、テストスイートで使用する同梱のフィクスチャ動画からのものです（すべての呼び出しと応答については demo/transcript.md を参照してください）。

get_transcript { "video": "kM3pLz8QwT0", "format": "segments", "include_timestamps": true }（抜粋）：

{
  "video": {
    "id": "kM3pLz8QwT0",
    "url": "https://www.youtube.com/watch?v=kM3pLz8QwT0",
    "title": "How Solar Panels Actually Work (Explained Simply)",
    "channel": "Bright Circuits",
    "durationSeconds": 552,
    "duration": "9:12",
    "viewCount": 1843291,
    "publishDate": "2025-03-14T07:00:12-07:00",
    "category": "Education",
    "isLive": false
  },
  "transcript": {
    "language": "en",
    "languageName": "English",
    "autoGenerated": false,
    "translatedFrom": null,
    "matchedPreference": true,
    "format": "segments",
    "segmentCount": 128,
    "wordCount": 870,
    "truncated": false,
    "segments": [
      { "start": 0, "duration": 4.116, "time": "0:00", "text": "Hey everyone, welcome back to Bright Circuits." },
      { "start": 4.2, "duration": 4.116, "time": "0:04", "text": "Today we're answering a question I get" }
    ]
  },
  "availableLanguages": [
    { "languageCode": "en", "languageName": "English", "autoGenerated": false, "translatable": true },
    { "languageCode": "es", "languageName": "Spanish", "autoGenerated": false, "translatable": true },
    { "languageCode": "en", "languageName": "English", "autoGenerated": true, "translatable": true }
  ],
  "translationLanguagesCount": 18
}

get_video_chapters（投稿者によるチャプターがない動画の場合。自動字幕のみ）。チャプターはトランスクリプトから生成されます。

#	開始	タイトル（特徴的なキーワード）
1	0:00	スターター、水、グラム
2	2:00	オートリーズ、グラム、温かい
3	4:11	ストレッチ、折りたたみ、一次発酵
4	5:52	冷やす、側面、表面
5	9:34	ふた
6	10:30	冷ます、切る、クラム

summarize_transcript { "video": "kM3pLz8QwT0", "max_points": 6 }（抜粋）：

• 要点： [2:32] 十分なエネルギーを持つ光子がシリコンに当たると、電子が弾き出され、そこに正孔が残ります。 · [5:09] ソーラーパネルは直流を生成しますが、家庭や電力網では交流が使われます。 · [6:52] 家庭用バッテリーは、日中に余った太陽光エネルギーを蓄え、夕方に使えるようにします…
• キーワード： パネル、セル、インバーター、光子、太陽光、エネルギー、バッテリー、電流、ソーラーパネル、電子
• チャプターの箇条書きでは、投稿者による7つのチャプター（「シリコン太陽電池の内部」、「インバーターと電力網」など）を使い、それぞれに箇条書きが2つあります。
• 引用： 「インバーターは直流を、電力網の電圧と周波数に正確に合った交流に変換します。」 [5:18]

動作の仕組み

トランスクリプト

サーバーは、人気のPythonライブラリ youtube-transcript-api と同じ方法でトランスクリプトを取得します。

1. 視聴ページを読み込みます。YouTubeにEUのCookie同意ページが表示された場合は、同意します。reCAPTCHAページが表示された場合は、REQUEST_BLOCKED として報告されます。また、このページからInnerTube APIキー、公開日、カテゴリ、チャプターマーカーも取得します。
2. ANDROID クライアントコンテキストで、InnerTubeのplayer APIを呼び出します。動画の詳細と captionTracks が返されます。再生可能状態は、上記のエラーコード（非公開、年齢制限、利用不可、再生不可、「ボットではないことを確認してください」）に対応付けられます。
3. トラックを選択します。優先する言語を順に確認し、それぞれについて手動字幕を自動生成字幕より優先し、基本言語との一致（en-GB → en）より正確なコードの一致を優先します。その後、timedtextファイルをダウンロードします。サーバーはsrv1 XML、srv3 XML、json3を解析します。

動画に対する3つのリクエストは、1つのプロキシセッションを通じて行われます。YouTubeは、字幕URLをリクエストしたIPに紐付けて署名するためです。

YouTubeのIPブロックを回避する

YouTubeは、クラウドのIPの大半をブロックします。Apifyの実現可能性調査では、直接リクエストで取得できたテスト動画は5本中1本でした。Apifyのデータセンタープロキシでは5本中4本が取得でき、残りの動画には単にトランスクリプトがありません。このため、Apifyプラットフォームでは、このサーバーはすべてのYouTubeリクエストをApify Proxy経由（デフォルトではデータセンター）にルーティングし、スティッキーセッションと undici の ProxyAgent を使用します。YouTubeがセッションをブロックした場合（429、captcha、ボットチェック、空の字幕ファイル、ネットワークエラー）、サーバーはそのセッションを破棄し、1回の呼び出しにつき最大5セッションまで、新しいIPで再試行します。正常なセッションは、後続の呼び出しでも再利用されます。

文字起こしから生成されるチャプター

動画に作成者が設定したチャプターがない場合、サーバーは TextTiling 方式で文字起こしを分割します。

1. 文字起こしを20～60秒の時間ブロックに分割し、各ブロックの TF-IDF ベクトルを作成します。
2. ブロック間の各境界で、境界より前の2つのブロックと、後の2つのブロックの語彙を比較します（コサイン類似度）。大きく低下した場合は、トピックが変わったことを示します。
3. 最低チャプター長を満たす範囲で、最も大きく低下した境界を採用します。その後、平均よりかなり長いチャプターがあれば、さらに分割します（時間ウィンドウによるフォールバック）。
4. 各境界を最も近い文の開始位置に合わせます。各チャプターには、他のチャプターとの差別化につながるキーワードを使ったタイトルを付け、最も中心的な文を添えます。

LLM を使わない要約

1. 文を作成します。句読点のある字幕は句読点で分割します。自動字幕には句読点がないため、単語ごとに時間を再設定し、談話標識（「so」「now」「next」など）や間の部分で短いチャンクに分割します。「[Music]」形式のタグは削除します。
2. TextRank を使って文に順位を付けます。TF-IDF コサイン類似度で重み付けしたグラフ上で PageRank を実行します。極端に短い断片は重みを下げます。
3. MMR（Maximal Marginal Relevance）を使って重要なポイント、チャプターの箇条書き、引用を選び、類似した内容が重複しないようにします。その後、時系列順に戻します。
4. 1分単位のウィンドウにわたる IDF で重み付けし、キーワードの頻度を評価します。選択済みのバイグラムに含まれるユニグラムは除外します。

この方法は決定的で透明性が高く、高速です。文字起こしを取得した後、数ミリ秒で処理できます。話者自身の言葉を引用するため、幻覚を起こしません。

制限事項

• 公開字幕のみ。 非公開、メンバー限定、年齢制限付きの動画は、明確なエラーコードとともに失敗します。サーバーがサインインすることはありません。
• 品質は字幕に左右されます。 自動生成字幕には句読点がなく、認識エラーも含まれます。要約と派生チャプターではこれらに対応しますが、作成者が用意した字幕のほうが文の品質は高くなります。
• 抽出型であり、抽象型ではありません。 要約では文字起こし内の文を引用し、言い換えは行いません。ストップワードリストとステミングは英語向けに調整されています。他の言語でも動作しますが、キーワードに多少ノイズが増えます。
• 検索対象は動画のみです。 チャンネル、プレイリスト、Shorts の棚は対象外で、「他のユーザーが視聴した動画」のおすすめも含まれません。「3週間前」などの相対日付は、YouTube の表示どおりにそのまま返されます。
• 非公式のエンドポイントです。 InnerTube と timedtext は YouTube 公式アプリが使用する API ですが、文書化されておらず、変更される場合があります。サーバーはバックオフ付きで再試行し、プロキシをローテーションします。応答はメモリ内に10分間キャッシュされます。
• ライブ配信。 配信中のライブストリームは、終了するまで通常、文字起こしがありません。

FAQ

YouTube Data API キーや Google アカウントは必要ですか？ いいえ。このホスト型サーバーを呼び出すには、Apify アカウントとトークンだけが必要です。

どの言語に対応していますか？ YouTube に字幕があるすべての言語に対応しています。["de", "en"] のような優先順位リストを渡してください。該当する言語がない場合は、メモを添えて利用可能な最適な字幕トラックを返します。ただし、fallback_to_any_language: false を設定した場合は除きます。translate_to を指定すると、YouTube が字幕トラックを機械翻訳します。

動画の長さに上限はありますか？ 固定の上限はありません。文字起こしの長さにかかわらず、transcript イベント1件分の料金がかかります。非常に長い動画では、max_chars または summarize_transcript を使って、エージェントのコンテキストを小さく保ってください。

REQUEST_BLOCKED が表示されたのはなぜですか？ この呼び出しでサーバーが試したすべてのプロキシ IP を、YouTube が拒否しました。通常は一時的なため、少し待ってから再試行してください。ブロックされた呼び出しには課金されません。

データは保存されますか？ いいえ。サーバーはステートレスで、短時間のメモリ内キャッシュのみを保持します。データセットやキーバリューストアには何も書き込みません。

セルフホストできますか？ はい。以下を参照してください。住宅用 IP であれば、通常 YouTube に直接アクセスできます。クラウドサーバーでは、YT_PROXY_URL を設定してください。

セルフホストと開発

npm install
npm run build
npm start              # MCP over stdio
npm run start:http     # Streamable HTTP at http://127.0.0.1:3000/mcp (GET / and /health = readiness)
npm test               # build + unit tests + MCP smoke test, all offline against recorded fixtures

環境変数	デフォルト	用途
PORT / HOST	3000 / 127.0.0.1	HTTP バインド（--http）。--port、--host も指定できます
YT_PROXY_URL	(未設定)	独自のプロキシ。カンマ区切りの http://user:pass@host:port URL を指定します。セッションごとに固定 URL を 1 つ使用し、ラウンドロビンで切り替えます
YT_PROXY	(未設定)	off にすると、Apify 上でもプロキシを無効にします
YT_PROXY_GROUPS / YT_PROXY_COUNTRY	datacenter / any	Apify Proxy のグループ（例：RESIDENTIAL）と、プラットフォーム上の国コード
YT_PROXY_ATTEMPTS	5	REQUEST_BLOCKED を返すまでに、呼び出しごとに試行するプロキシセッション数
YT_FIXTURES	(未設定)	すべての YouTube リクエストをフィクスチャディレクトリから提供します（オフラインモード。テストで使用）
HTTP_TIMEOUT_MS	8000	リクエストごとのタイムアウト（停止したプロキシ出口は待機せずに切り替えます）
HTTP_MAX_RETRIES	2	直接接続（プロキシなし）の場合のみ、5xx／タイムアウト時にその場で再試行します。プロキシ経由の呼び出しではセッションを切り替えます
YT_KEEP_ALIVE_MS	60000	呼び出し間にプロキシトンネルを維持するアイドル時間
YT_SLOW_SESSION_MS	6000	処理にこれ以上かかったプロキシセッションは終了し、次の呼び出しで新しい IP アドレスを取得します
CACHE_TTL_MS	600000	メモリー内キャッシュの TTL（0 で無効化）
BILLING	(未設定)。Docker イメージでは apify	apify はイベントごとの従量課金 Actor.charge() を有効にします。log は課金情報を stderr に出力するだけです

Apify 上（Standby モード）。 APIFY_IS_AT_HOME が設定されている場合、サーバーは Actor.init() を呼び出し、HTTP モードを強制して、0.0.0.0:$ACTOR_WEB_SERVER_PORT で待ち受けます。GET / は Standby の準備状況プローブに応答し、MCP は /mcp で提供されます。YouTube へのトラフィックは Apify Proxy を経由します。HTTP サーバー自体には認証機能がありません。Apify 上では、プラットフォームが API トークンを使ってリクエストを認証します。localhost 以外でセルフホストする場合は、認証プロキシの背後に配置してください。

テスト

• ユニットテスト（test/unit/*.test.mjs、node --test）は、実際の YouTube の応答を再現した手作りのフィクスチャを使って実行します。対象には、ANDROID player JSON、srv1/json3 timedtext、continuation と shelf を含む WEB 検索ページ、reCAPTCHA ページを含む視聴ページ、すべてのエラーステータスが含まれます。解析、トラックの選択、説明文とそこから導出されるチャプター、TextRank と要約、検索の params エンコード、エラーのマッピング、プロキシセッションの切り替えをテストします。
• MCP スモークテスト（test/smoke.mjs）は、YT_FIXTURES を使って stdio 経由でサーバーを起動し、ツールを一覧表示して各ツールを呼び出します（エラーパスを含む）。課金が成功した呼び出しに対してのみ行われること、HTTP モードと準備状況プローブを確認し、demo/transcript.{json,md} を書き込みます。
• ライブリモートテスト（test/live-remote.mjs、npm test の対象外）は、デプロイ済みの Standby URL に対して実行します。MCP_URL=… APIFY_TOKEN=… node test/live-remote.mjs。
• npm run fixtures は scripts/make-fixtures.mjs から test/fixtures/ を再生成します。

.actor/        actor.json (Standby, /mcp), input_schema.json (empty), output_schema.json (MCP endpoint)
Dockerfile     apify/actor-node:20, multi-stage TypeScript build, BILLING=apify
src/
  index.ts       entry: stdio or stateless Streamable HTTP; Apify Standby wiring
  server.ts      MCP tool registrations (zod schemas, error payloads, billing)
  youtube.ts     watch page → InnerTube player (ANDROID) → timedtext; track selection; error mapping
  transcript.ts  srv1/srv3/json3 parsing; text / SRT formatting
  search.ts      InnerTube search, protobuf filter params, continuation paging
  chapters.ts    description chapter parser; TextTiling-style derived chapters
  text.ts        tokenizer, stemmer, sentences, TF-IDF, TextRank, keywords
  summary.ts     extractive summary (key points, chapter bullets, quotes, stats)
  http.ts        timeouts/retries, proxy sessions + rotation, fixture mode
  proxy.ts       Apify Proxy / YT_PROXY_URL selection
  fixtures.ts    offline fixture resolver
  billing.ts     chargeEvent() → Actor.charge() when BILLING=apify
  util.ts        error codes, cache, id/URL parsing, time helpers

ライセンス

MIT