YouTube Transcript Remote MCP Server

YouTube 動画の字幕を取得する Remote MCP サーバー。Cloudflare Workers 上で動きます。

ergut/youtube-transcript-mcp をフォーク元とした、自前ホスティング用の構成です。

本家からの変更点

• Streamable HTTP 対応 — /mcp を MCP 仕様（2025-06-18 / 2025-03-26 / 2024-11-05）に準拠させ、Claude アプリのカスタムコネクタから直接繋がるようにしました。通知（notifications/initialized など）には 202 を返し、本文を返しません。仕様上、通知にレスポンスを返してはいけないためです。

• 未使用依存の削除 — 元は GitHub OAuth テンプレートの流用で、octokit / hono / agents / @modelcontextprotocol/sdk など9個の依存と3ファイルが未使用のまま残っていました。実際に使うのは youtube-transcript と url-parse だけです。

• 言語自動検出の修正 — 下記参照。

• ping / tools.listChanged に対応、ツール失敗は MCP 慣例どおり isError: true を含む結果として返却。

言語自動検出のバグ修正

元の実装は、字幕が見つからないと12言語 × 3リトライ = 最大36サブリクエストを順に投げていました。早期打ち切りの判定 isLanguageRelatedError() は存在しましたが、リトライ層がエラーを Failed to fetch transcript for ... という文字列で包むため、その中の "transcript" に必ずマッチしてしまい、一度も発火しない実質デッドコードでした。

Cloudflare Workers 無料プランのサブリクエスト上限は50なので、これは上限に迫るうえ、MCP クライアント側のタイムアウトにも掛かります。

修正として、メッセージの部分一致ではなく youtube-transcript が投げるエラークラスで分類するようにしました。さらに、YouTube が「利用可能な言語一覧」をエラーに含めて返すため、総当たりをやめてその一覧を使います。

計測値（字幕取得に失敗するケース）:

Related MCP server: YouTube Transcript MCP Server

デプロイ手順

Cloudflare アカウントが必要です。GitHub Actions 経由（手元に何も入れずに済む）と、手元で実行する方法の2通りあります。

方法A: GitHub Actions（推奨）

1. Cloudflare の API トークン作成画面 で "Edit Cloudflare Workers" テンプレートからトークンを作成します。必要な権限は Workers Scripts:Edit と Workers KV Storage:Edit です。

2. このリポジトリの Settings → Secrets and variables → Actions で、CLOUDFLARE_API_TOKEN として登録します。アカウントを複数お持ちの場合は CLOUDFLARE_ACCOUNT_ID も登録してください。

3. Actions タブ → "Deploy to Cloudflare Workers" → Run workflow。

KV namespace の作成と wrangler.toml への id 反映はワークフローが自動で行うので、手動編集は不要です。デプロイ後はスモークテストまで自動実行され、払い出された URL が実行サマリに表示されます。以降 main への push でも自動デプロイされます。

方法B: 手元で実行する

git clone https://github.com/iakito-dev/youtube-transcript-mcp
cd youtube-transcript-mcp
npm install

# Cloudflare にログイン（ブラウザが開きます）
npx wrangler login

# KV namespace を作成する
npx wrangler kv namespace create TRANSCRIPT_CACHE

最後のコマンドが出力する id を wrangler.toml の kv_namespaces.id に貼り付けてから:

npm run deploy

https://youtube-transcript-mcp.<あなたのサブドメイン>.workers.dev が払い出されます。

動作確認

./scripts/smoke-test.sh https://<あなたのURL>

MCP ハンドシェイク3項目と、実際の字幕取得を順に検証します。ハンドシェイクが通って字幕取得だけ失敗する場合は、デプロイは成功していて YouTube 側が Workers の IP を拒否している、という切り分けになります。

手動で確認する場合:

curl -X POST https://<あなたのURL>/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

get_transcript が1件返れば成功です。

Claude アプリへの登録

設定 → コネクタ → カスタムコネクタを追加 で、以下を指定します。

https://<あなたのURL>/mcp

登録後は、チャットに YouTube の URL を貼って「この動画を要約して」と頼むだけで、Claude が get_transcript を呼んで字幕を取得します。

mcp-remote 経由（Claude Desktop の claude_desktop_config.json）を使う場合:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["mcp-remote", "https://<あなたのURL>/mcp"]
    }
  }
}

ツール

get_transcript

トラッキングパラメータ（?si=、&t= など）は自動で除去されます。

制約事項

• 字幕のない動画は要約できません。 このサーバーは YouTube が持つ字幕（自動生成含む）を取得するだけで、音声の書き起こしは行いません。

• YouTube 側のボット検出を受ける可能性があります。 youtube-transcript は公式 API ではなく視聴ページのスクレイピングで動作するため、データセンター IP からのアクセスがブロックされることがあります。Cloudflare Workers の IP がこれに該当する場合、字幕取得が失敗します。この挙動は実環境にデプロイしてからでないと確認できません。

• 取得した字幕は KV に7日間キャッシュされます。

• 認証はありません。URL を知っていれば誰でも利用できます。気になる場合は Cloudflare Access などを前段に置いてください。

ライセンス

MIT（ergut/youtube-transcript-mcp の LICENSE を継承）