YouTube MCP Server

MCP サーバーは、YouTube を Claude Code に統合します。動画のトランスクリプト、検索、メタデータ、チャンネル情報、プレイリスト、コメント、急上昇動画、エンゲージメント分析、チャプター抽出、SponsorBlock 統合、そして「最も再生された」ヒートマップを提供します。YouTube Data API v3、youtube-transcript、SponsorBlock を使用しています。

クイックスタート

ステップ1: APIキーを取得する

1. Google Cloud Console にアクセスする

2. プロジェクトを作成する（既存のプロジェクトを選択してもよい）

3. YouTube Data API v3 を有効にする:

   • API ライブラリ にアクセス

   • 有効化 をクリック

4. APIキーを作成する:

   • 認証情報 にアクセス

   • 認証情報を作成 > APIキー をクリック

5. キーをコピーする（ステップ3で必要になります）

ステップ2: 前提条件をインストールする

• Node.js 18+ - ダウンロードはこちら

• Claude Code CLI - インストールガイド

ステップ3: MCP サーバーをインストールする

3.1 リポジトリをクローンする

git clone https://github.com/wynandw87/claude-code-youtube-mcp.git
cd claude-code-youtube-mcp

3.2 依存関係をインストールする

macOS / Linux / Windows:

npm install

注: 依存関係のインストールとサーバーのビルドは1つのステップで自動的に行われます。

3.3 Claude Code に登録する

インストールの適用範囲を選択してください:

YOUR_API_KEY を実際の YouTube Data API キーに置き換え、dist/index.js への絶対パスを使用してください。

ヒント: 絶対パスを取得するには、クローンしたディレクトリで次を実行します:

• macOS/Linux: echo "$(pwd)/dist/index.js"

• Windows: echo %cd%\dist\index.js

macOS / Linux:

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows (CMD):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows (PowerShell):

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

代替方法: npm helper を使用する（APIキーが環境変数に設定されている場合）

export YOUTUBE_API_KEY=YOUR_API_KEY
npm run install:claude

ステップ4: Claude Code を再起動する

変更を反映するには、Claude Code を閉じて再度開いてください。

ステップ5: インストールを確認する

claude mcp list

youtube が Connected ステータスで表示されれば成功です。

Related MCP server: youtube-research

機能

トランスクリプトとキャプション

• トランスクリプトを取得（get_transcript）- タイムスタンプ付きの動画の完全なトランスクリプトを取得、複数の言語に対応

• トランスクリプトを検索（search_transcript）- キーワードやフレーズが動画内のどこに登場するかをタイムスタンプ付きで検索

• クリーンなトランスクリプトを取得（get_clean_transcript）- SponsorBlock を使用してスポンサー、イントロ、アウトロ、無駄な部分を除去したトランスクリプト

• チャプターを抽出（extract_chapters）- 動画の説明からチャプターのタイムスタンプを解析

検索と発見

• 動画を検索（search_videos）- 日付、長さ、種別、並び順のフィルターに対応した完全な YouTube 検索

• チャンネル内を検索（search_within_channel）- 特定のクリエイターの動画を検索

• 急上昇中の動画を取得（get_trending_videos）- 地域とカテゴリごとの現在の急上昇動画

• チャンネルの動画を取得（get_channel_videos）- チャンネルの最近のアップロード動画を日付または再生回数で並べ替え

動画とチャンネルの情報

• 動画メタデータ（get_video_metadata）- タイトル、説明、長さ、再生回数、高評価数、タグなど

• チャンネル情報（get_channel_info）- 登録者数、動画数、説明、国

• プレイリストのアイテム（get_playlist_items）- プレイリスト内のすべての動画を、位置とメタデータ付きで取得

分析とエンゲージメント

• エンゲージメントを計算（calculate_engagement）- 公開統計から高評価率、コメント率、エンゲージメント率を計算

• 最も再生された部分（get_most_replayed）- 視聴者が最も見返す部分を示すヒートマップデータ

• 動画のコメント（get_video_comments）- 高評価数と返信数付きの上位コメント

ユーティリティ

• YouTube URL を解析（parse_youtube_url）- あらゆる形式の YouTube URL から動画・チャンネル・プレイリストの ID を抽出

使用方法

インストール後、トリガーフレーズを使って YouTube ツールを呼び出せます:

または自然な聞き方で:

• 「この YouTube 動画のトランスクリプトを取得して要約して」

• 「この動画の最も再生された部分はどこですか？」

• 「このチャンネルで TypeScript に関する最近の動画を見つけて」

• 「この動画の再生回数と高評価数は？」

• 「この動画のコメントを取得して感情を要約して」

• 「このチュートリアルのチャプターを見せて」

• 「スポンサー読み上げなしのクリーンなトランスクリプトを取得して」

• 「YouTube のゲームカテゴリで今急上昇しているのは？」

ツールリファレンス

parse_youtube_url

あらゆる形式の YouTube URL を解析して識別子を抽出します。APIキーは不要です。

パラメータ:

• url（string、必須）- 任意の YouTube URL または動画 ID

対応形式: youtube.com/watch?v=、youtu.be/、/shorts/、/embed/、/playlist?list=、/channel/、/@handle、/c/、/user/、動画 ID 単体

get_transcript

YouTube 動画の完全なトランスクリプト/キャプションを取得します。APIキーは不要です。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

• lang（string、任意）- キャプションの言語コード（デフォルト: "en"）

search_transcript

動画のトランスクリプト内でキーワードやフレーズを検索します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

• query（string、必須）- 検索するキーワードまたはフレーズ

• lang（string、任意）- キャプションの言語コード（デフォルト: "en"）

extract_chapters

動画の説明からチャプターのタイムスタンプを抽出します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

get_clean_transcript

SponsorBlock を使用して、スポンサー読み上げ、イントロ、アウトロ、無駄な部分を除去したトランスクリプトを取得します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

• lang（string、任意）- キャプションの言語コード（デフォルト: "en"）

get_most_replayed

視聴者が最も見返す部分を示す「最も再生された」ヒートマップデータを取得します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

注: ヒートマップデータを利用するには、約5万回以上の再生回数が必要です。

search_videos

完全なフィルター対応で YouTube を検索します。

パラメータ:

• query（string、必須）- 検索クエリ

• max_results（number、任意）- 結果の件数、1〜50（デフォルト: 10）

• order（string、任意）- "relevance"、"date"、"viewCount"、"rating"（デフォルト: "relevance"）

• duration（string、任意）- "short"（4分未満）、"medium"（4〜20分）、"long"（20分超）

• upload_date（string、任意）- "hour"、"day"、"week"、"month"、"year"

• type（string、任意）- "video"、"channel"、"playlist"（デフォルト: "video"）

get_video_metadata

YouTube 動画の詳細なメタデータを取得します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

戻り値: タイトル、説明、チャンネル、長さ、再生回数/高評価数/コメント数、タグ、カテゴリ、サムネイル、ライブ配信ステータスなど。

get_channel_info

YouTube チャンネルの情報を取得します。

パラメータ:

• url（string、必須）- YouTube チャンネルの URL、@handle、またはチャンネル ID

戻り値: タイトル、説明、登録者数/動画数/再生回数、国、カスタム URL、サムネイル。

get_playlist_items

YouTube プレイリスト内のすべての動画を取得します。

パラメータ:

• url（string、必須）- YouTube プレイリストの URL またはプレイリスト ID

• max_results（number、任意）- アイテム数、1〜50（デフォルト: 25）

get_channel_videos

YouTube チャンネルの最近の動画を取得します。

パラメータ:

• url（string、必須）- YouTube チャンネルの URL、@handle、またはチャンネル ID

• max_results（number、任意）- 動画数、1〜50（デフォルト: 25）

• order（string、任意）- "date"、"viewCount"（デフォルト: "date"）

get_trending_videos

現在急上昇中/人気の YouTube 動画を取得します。

パラメータ:

• region_code（string、任意）- ISO 3166-1 alpha-2 の国コード（デフォルト: "US"）

• category_id（string、任意）- YouTube カテゴリ ID（例: Music は "10"、Gaming は "20"、Science & Tech は "28"）

• max_results（number、任意）- 結果の件数、1〜50（デフォルト: 10）

search_within_channel

特定の YouTube チャンネル内で動画を検索します。

パラメータ:

• url（string、必須）- YouTube チャンネルの URL、@handle、またはチャンネル ID

• query（string、必須）- 検索クエリ

• max_results（number、任意）- 結果の件数、1〜50（デフォルト: 10）

get_video_comments

YouTube 動画のトップレベルコメントを取得します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

• max_results（number、任意）- コメント数、1〜100（デフォルト: 20）

• order（string、任意）- "relevance"、"time"（デフォルト: "relevance"）

calculate_engagement

YouTube 動画のエンゲージメント指標を計算します。

パラメータ:

• url（string、必須）- YouTube 動画の URL または動画 ID

戻り値: 再生回数、高評価数、コメント数、高評価率、コメント率、総合エンゲージメント率。

仕組み

この MCP サーバーは stdio トランスポート経由で Claude Code に接続し、15個のツールを提供します:

注: 5つのツールはAPIキーなしで動作します（トランスクリプト、SponsorBlock、ヒートマップ、URL解析）。残りの10個はYouTube Data API v3キーが必要です。

設定

環境変数

YouTube API クォータ

YouTube Data API v3 には1日あたり 10,000 ユニット のクォータがあります。各ツールの消費量は次のとおりです：

ヒント: 検索オペレーションが最もコストが高くなります。最近のアップロードだけが必要な場合は、search_within_channel（100ユニット）の代わりに get_channel_videos（1ユニット）を使用してください。

トラブルシューティング

APIキーを修正する

間違ったAPIキーを入力した場合は、削除して再インストールしてください：

claude mcp remove youtube

その後、上記の手順3.3のコマンドを使って再インストールしてください（最初にインストールしたときと同じスコープを使用してください）。

MCPサーバーが表示されない

サーバーがインストールされているか確認してください：

claude mcp list

一覧にない場合は、手順3に従ってインストールしてください。

サーバーが起動しない

1. APIキーが有効かどうかを Google Cloud Console で確認してください

2. YouTube Data API が有効になっているか確認してください：

   • API Library に移動します

   • 「有効」と表示されているはずです

3. Node.js のバージョンを確認してください（18+が必要です）：

   node --version

4. サーバーがビルドされていることを確認してください — dist/index.js がない場合は、npm install を再度実行してください

接続エラー

1. dist/index.js が存在するか確認してください — 存在しない場合は npm install を実行してください

2. claude mcp add コマンド内のパスが絶対パスであることを確認してください

3. 設定を変更した後は Claude Code を再起動してください

クォータ超過

「quotaExceeded」エラーが表示される場合：

• 太平洋時間の午前0時まで待つ（クォータは毎日リセットされます）

• 別のAPIキーを使用する

• 検索ツール（100ユニット）よりも低コストのツール（1ユニットの get_video_metadata）を優先する

トランスクリプトが利用できない

一部の動画ではトランスクリプトが無効になっています。get_transcript ツールは明確なエラーメッセージを返します。次の点を試してください：

• 別の言語コード（例：lang: "es"）

• 手動の字幕がない場合でも、自動生成された字幕が利用できる場合があります

タイムアウトエラー

接続が遅い場合は、YOUTUBE_TIMEOUT 環境変数を増やしてください：

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_KEY -e YOUTUBE_TIMEOUT=60000 -- node /path/to/dist/index.js

現在の設定を表示

claude mcp list

コントリビューション

Pull Request を歓迎します！シンプルで初心者にやさしいものにしてください。

ライセンス

MIT

Claude Code コミュニティのために作られました。