Youtube Transcript Mcp

YouTube Transcript MCP サーバー

Claude Code 向けに、YouTube 動画の文字起こしを取得する Model Context Protocol（MCP）サーバーです。このサーバーを使うと、コンテンツを手動でダウンロードしたりコピーしたりせずに、動画の文字起こしを簡単に抽出できます。動画コンテンツの分析、講演の要約、教育動画からの情報抽出に最適です。

• この MCP サーバーについてのブログ記事：One More Piece Built: Adding YouTube Analysis to My Learning Iron Man Suit
• npm パッケージ：‌@fabriqa.ai/youtube-transcript-mcp
• 作成者：Cengiz Han

特長

• 動画の文字起こしを取得：字幕が利用可能な任意の YouTube 動画から、文字起こし全文を抽出します
• 複数の URL 形式に対応：一般的なすべての YouTube URL 形式（youtube.com、youtu.be など）に対応します
• タイムスタンプに対応：文字起こしの出力にタイムスタンプを含めるかどうかを選べます
• 言語を選択：利用可能な場合、特定の言語で文字起こしをリクエストできます
• エラー処理：文字起こしがない動画や無効な URL を適切に処理します
• コンテキストを効率的に使用：不要な動画メタデータを読み込まず、文字起こしだけを取得します

インストール

オプション A：npm からインストール（推奨）

npm install -g @fabriqa.ai/youtube-transcript-mcp

インストール後、サーバーはグローバルに利用可能になります。次のコマンドを実行して設定できます。

# The package will be installed in your global node_modules
# Typically: /usr/local/lib/node_modules/@fabriqa.ai/youtube-transcript-mcp

オプション B：ソースからインストール

1. このリポジトリをクローンします。

git clone https://github.com/hancengiz/youtube-transcript-mcp.git
cd youtube-transcript-mcp

2. 依存関係をインストールします。

npm install

設定

npm 経由でインストールした場合（推奨）：

オプション 1：Claude Code CLI を使用（最も簡単）

推奨：マシン全体にインストール

# Add the MCP server for all projects (machine-wide)
claude mcp add --scope user youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

スコープの選択肢について：

Claude Code は MCP サーバーに対し、3 つの設定スコープに対応しています。

• --scope user（推奨）- マシン全体

  • すべてのプロジェクトとディレクトリで利用可能
  • 一度設定すれば、どこでも使用可能
  • 複数のプロジェクトで定期的に使うツールに最適

• --scope local（デフォルト）- プロジェクト固有

  • 現在のディレクトリとそのサブディレクトリでのみ利用可能
  • プロジェクト固有の MCP サーバーに便利
  • プロジェクトごとに設定が必要

• --scope project - 明示的なプロジェクト設定

  • 特定のプロジェクト設定に使用

使用例：

# Machine-wide (recommended for youtube-transcript)
claude mcp add --scope user youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

# Project-specific (if you prefer)
claude mcp add --scope local youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

# Or use the convenience script
npx @fabriqa.ai/youtube-transcript-mcp/update-config.js

オプション 2：手動で設定

~/.claude.json に追加します。

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "@fabriqa.ai/youtube-transcript-mcp@latest"
      ]
    }
  }
}

これは npx を使って、パスを指定せずにグローバルインストール済みのパッケージを自動的に実行します。

クイックセットアップスクリプト（任意）：

npm 経由でインストールした後、付属の設定スクリプトを使って ~/.claude.json を自動更新できます。

npx @fabriqa.ai/youtube-transcript-mcp/update-config.js

ソースからインストールした場合は、次のとおりです。

node update-config.js

これにより npx を使って MCP サーバーが自動的に追加され、すべてのプロジェクトでマシン全体から利用できるようになります。

手動設定：

Claude Desktop の場合は、~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "@fabriqa.ai/youtube-transcript-mcp@latest"
      ]
    }
  }
}

使用方法

設定後、Claude Code を再起動します。次のツールが利用可能になります。

1. get-transcript

YouTube 動画の文字起こしを取得します。

パラメーター：

• url（必須）：YouTube 動画の URL または動画 ID
• lang（任意）：文字起こしの言語コード（例：'en'、'es'、'fr'）。デフォルト：動画のデフォルト言語
• include_timestamps（任意）：出力にタイムスタンプを含めます。デフォルト：true

対応する URL 形式：

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://m.youtube.com/watch?v=VIDEO_ID
• VIDEO_ID（11 文字の動画 ID のみ）

例：

Can you get the transcript from https://www.youtube.com/watch?v=LCEmiRjPEtQ?

Get the transcript from this video without timestamps: https://youtu.be/LCEmiRjPEtQ

Summarize the key learnings from this Andrej Karpathy talk: https://www.youtube.com/watch?v=LCEmiRjPEtQ

2. get-transcript-languages

動画で利用できる文字起こしの言語を確認します。

パラメーター：

• url（必須）：YouTube 動画の URL または動画 ID

例：

What transcript languages are available for https://www.youtube.com/watch?v=LCEmiRjPEtQ?

使用例

Claude Code でこの MCP サーバーを使用する例を紹介します。

1. 動画を要約するために文字起こしを抽出する：

   Give me the key learnings from this Andrej Karpathy talk: https://www.youtube.com/watch?v=LCEmiRjPEtQ
   

2. 動画の特定のトピックを分析する：

   Get the transcript from https://www.youtube.com/watch?v=LCEmiRjPEtQ and extract all mentions of "LLM" and "agents"
   

3. 異なる言語で文字起こしを取得する：

   What transcript languages are available for https://www.youtube.com/watch?v=LCEmiRjPEtQ?
   

4. タイムスタンプなしで引用を抽出する（長い動画の場合）：

   Get the transcript without timestamps from this video: https://www.youtube.com/watch?v=LCEmiRjPEtQ
   

   注：この 60 分の動画では、タイムスタンプなしの場合は約 19k トークン、タイムスタンプありの場合は約 30k トークンが生成されます。

5. 調査とコンテンツ作成：

   Get 3 key quotes from Andrej Karpathy about partial autonomy apps from https://www.youtube.com/watch?v=LCEmiRjPEtQ
   

応用：Claude Code のサブエージェントでコンテキストを効率的に活用する

動画の分析でコンテキストを 90% 節約できます！

Claude Code は、YouTube 動画を分離されたコンテキストで分析し、分析結果のみをメインの会話に返す、特化型サブエージェントに対応しています。これにより、大量の文字起こしでコンテキストウィンドウを埋めることなく、多くの動画を分析できます。

簡単な例

次のようにすると（コンテキストが 20k 以上のトークンで埋まります）：

Get the transcript and analyze this video: [URL]

代わりに次のようにします（コンテキストで使うのは約 2k トークンのみです）：

Use sub-agent to analyze this video: [URL]

youtube-transcript-analyzer エージェント

この特化型エージェントは、次のことができます。

• ✅ 独自の分離されたコンテキストで文字起こしを取得します
• ✅ 内容を徹底的に分析します
• ✅ 分析結果のみを返します
• ✅ 1 回のセッションで 10 本以上の動画を分析できます
• ✅ コンテキストを整理し、分析に集中できます

詳細はこちら

📖 Claude Code サブエージェント完全ガイド

このガイドでは、次の内容を扱います。

• サブエージェントがコンテキストを節約する仕組み（例付き）
• youtube-transcript-analyzer エージェントの完全なセットアップ手順
• そのままコピーして使える設定ファイル
• 実際の使用例とワークフロー
• 複数の動画を効率よく分析するための応用ヒント

最適な対象： 研究者、コンテンツクリエイター、学生、および 1 回のセッションで複数の動画を分析するすべての方。

使用例

• コンテンツの要約：1 時間に及ぶ技術講演（例：Andrej Karpathy の「Software in the Era of AI」）から重要な学びを抽出します
• 調査：視聴せずに、カンファレンスの講演、学術講義、教育コンテンツを分析します
• コンテンツ作成：ブログ記事や記事に使うため、動画の内容から正確な引用や参照を取得します
• 学習と教育：講義の内容をすばやく復習し、主要な概念や例を抽出します
• アクセシビリティ：動画の内容を検索可能で読みやすいテキスト形式に変換します
• インタビュー分析：ポッドキャストのインタビューやパネルディスカッションから引用や知見を抽出します
• 技術文書の作成：チュートリアル動画からコード例や技術的な説明を取得します

メリット

• 時間の節約：動画を最後まで視聴せずに内容を取得できます
• コンテキストの効率化：必要なテキストコンテンツだけを抽出できます
• 形式の柔軟性：タイムスタンプを含めるかどうかを選択できます
• 多言語対応：利用可能な場合、異なる言語の文字起こしにアクセスできます
• 簡単な連携：Claude Code 向けのシンプルな URL ベースのインターフェースです

技術的な詳細

• @modelcontextprotocol/sdk を使用して構築されています
• カスタム開発の YouTube 字幕ライブラリ（yt-lib/）を使用します
• 字幕の取得に外部依存関係はありません（ネイティブの fetch API を使用）
• stdio を介して通信するローカルの Node.js プロセスとして実行されます
• 字幕が利用可能なすべての YouTube 動画に対応しています
• YouTube の Innertube API と直接連携し、信頼性の高い字幕アクセスを実現します

制限事項

MCP プロトコルトークンの上限

MCP（Model Context Protocol）のインフラストラクチャには、Claude のコンテキストウィンドウを保護し、パフォーマンスの問題を防ぐため、25,000 トークンの応答上限があります。この上限は YouTube やこのツールではなく、MCP プロトコル層によって設定されています。

この上限の影響：

• タイムスタンプを有効にした場合、非常に長い動画（通常 60 分以上）の字幕がこの上限を超えることがあります
• YouTube からの字幕取得は成功しますが、サイズが大きすぎると MCP によって応答がブロックされます

症状：

Error: MCP tool "get-transcript" response (30131 tokens) exceeds
maximum allowed tokens (25000). Please use pagination, filtering,
or limit parameters to reduce the response size.

解決策：

1. タイムスタンプを無効にする（長い動画の場合に推奨）：

   Get the transcript without timestamps from https://www.youtube.com/watch?v=VIDEO_ID
   

   通常、これにより応答サイズが 20～30％減少し、ほとんどの動画が上限内に収まります。

2. 短い動画をリクエストする（60 分未満であれば、通常はタイムスタンプ付きでも問題ありません）

3. チャンク単位で処理する：非常に長い動画の場合は、MCP ツールを介さず、プログラムから字幕データを処理する必要があることがあります

実例（Andrej Karpathy の講演）：

• https://www.youtube.com/watch?v=LCEmiRjPEtQ（60 分の技術講演）
• タイムスタンプあり：約 30,000 トークン ❌（25,000 トークンの上限を超過）
• タイムスタンプなし：約 19,000 トークン ✅（問題なく動作）

**回避策：**長い動画の場合は、「タイムスタンプなしで字幕を取得して」と依頼してください。

トラブルシューティング

Claude Code にサーバーが表示されない

1. 設定ファイル内のパスが正しいことを確認します
2. Node.js がインストールされ、PATH に設定されていることを確認します
3. 依存関係がインストールされていることを確認します：npm install
4. Claude Code を完全に再起動します
5. Claude Code のログにエラーメッセージがないか確認します

「字幕を利用できません」というエラー

• すべての YouTube 動画に字幕があるわけではありません
• 一部の動画では、特定の言語の自動生成字幕のみが利用できます
• 非公開または制限付きの動画にはアクセスできません
• YouTube で動画の字幕が有効になっているか確認してください

言語が見つからない

• get-transcript-languages ツールを使用して、利用可能な言語を確認します
• よく使われる言語コード：「en」、「es」、「fr」、「de」、「ja」、「ko」、「pt」、「ru」、「zh」など
• すべての動画に、すべての言語の字幕があるわけではありません

無効な URL エラー

• 有効な YouTube URL 形式を使用していることを確認します
• 動画 ID は正確に 11 文字である必要があります
• 動画が存在し、一般にアクセス可能であることを確認します

開発

サーバーを変更または拡張するには、以下の手順に従います。

1. index.js を編集して、新しいツールを追加するか、既存のツールを変更します
2. ListToolsRequestSchema ハンドラーを更新して、新しいツールを登録します
3. CallToolRequestSchema ハンドラーに対応するハンドラーを追加します
4. npm test を実行して変更をテストします
5. サーバーを再起動し（Claude Code を再起動して）、変更をテストします

テスト

テストスイートを実行します。

npm test

以下を検証します。

• Claude API の JSON スキーマへの準拠
• ツールの登録と一覧表示
• 字幕取得機能
• エラー処理
• URL の解析

ライセンス

MIT

作者

Cengiz Han が作成しました

コントリビューション

この MCP サーバーの改善につながる Issue やプルリクエストをお気軽にお寄せください。