kirbah-mcp-youtube

YouTube Data MCP サーバー (@kirbah/mcp-youtube)

AI エージェント専用に設計された、実運用グレードの YouTube Data MCP サーバーです。

LLM を冗長なデータで溢れかえらせる標準的な API ラッパーとは異なり、このサーバーは YouTube の重たいペイロードの膨張を取り除きます。コンテキストウィンドウのトークンを大幅に節約し、キャッシュによって 1 日の API クォータを保護し、ワークフローを壊さずに安定して動作するように設計されています。

なぜこのサーバーを選ぶのか？

ほとんどの MCP サーバーは週末プロジェクトです。@kirbah/mcp-youtube は、信頼性が高く、毎日使えて、コスト効率の良いエージェントワークフローのために作られています。

🎯 生のデータだけでなく、自分のチャンネルについてのフィードバックが欲しいですか？ CreatorLens をチェックしてください。これはこの MCP を基盤に構築されたコンパニオン Claude Skill で、単なる数値ではなく、実際のストラテジストのフレームワークを用いて、よくある成長問題（弱い フック、悪いサムネイル、伸び悩む動画）を診断します。

📉 1. トークン（およびコンテキストウィンドウ）を最大 87% 節約

生の YouTube API は、ネストされた eTag、冗長なサムネイル、LLM には不要なローカライズデータで埋め尽くされた巨大な JSON ペイロードを返します。このサーバーはデータを構造化し、LLM が推論するために必要なものだけを過不足なく提供します。

%%{init: { "theme": "base", "themeVariables": { "xyChart": { "plotColorPalette": "#ef4444, #22c55e" } } } }%%
xychart-beta
    title "Token Consumption (Lower is Better)"
    x-axis ["getVideoDetails", "searchVideos", "getChannelStats"]
    y-axis "Context Tokens" 0 --> 1200
    bar "Raw YouTube API" [854, 1115, 673]
    bar "MCP-YouTube (Optimized)" [209, 402, 86]

API メソッド	生の YouTube トークン	MCP-YouTube トークン	トークン削減量	データサイズ
getChannelStatistics	673	86	約87%削減	1.9 KB ➔ 0.2 KB
getVideoDetails	854	209	約75%削減	2.9 KB ➔ 0.6 KB
searchVideos	1115	402	約64%削減	3.4 KB ➔ 1.2 KB

（気になりますか？ examples フォルダーで生の API レスポンスと最適化された出力を比較できます）。

🛡️ 2. API クォータを保護（スマートキャッシュ）

YouTube Data API には厳しい 1 日の上限（10,000 クォータユニット）があります。LLM がループにはまったり、同じ質問を繰り返したりすると、標準的なサーバーは数分で API 制限を使い果たしてしまいます。 このサーバーにはオプションの MongoDB キャッシュレイヤーが含まれています。エージェントが動画の詳細をリクエストしたり、同じトレンド動画を 2 回検索したりしても、サーバーはキャッシュから応答します。消費する API クォータポイントは 0 です。

🏗️ 3. 本番グレード & 活発にメンテナンス

MCP ツールが AI クライアントをクラッシュさせるのにうんざりしていませんか？このサーバーは、極めて堅牢な依存関係となるように作られています：

• 97% のテストカバレッジ： 包括的なユニットテストを実施しています（Codecov バッジをご確認ください）。
• リントエラー/警告ゼロ： 厳格でクリーンなコードを強制します（npm run lint が 100% パスします）。
• アクティブなセキュリティ： 自動化された Dependabot パッチ適用により、基盤となるライブラリに既知の脆弱性が残されることはありません。
• 厳格な型安全性： Zod バリデーションと堅牢な MCP TypeScript Starter アーキテクチャを使用して構築されています。

---

クイックスタート：インストール

🟢 ゼロコンフィグモード（API キー不要）

とりあえず文字起こしを取得したいだけですか？ このサーバーは設定なしで即使えます！インストールするだけで動作します。後から YouTube API キーを追加すると、ディープサーチと分析が利用可能になります。

このサーバーをインストールする最も簡単な方法は、Glama サーバーページにある 「Add to Claude Desktop」 ボタンをクリックすることです。

手動で設定する場合（例：Cursor での設定）、以下の最小構成を追加するだけです：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"]
    }
  }
}

✨ ヒント： ゼロコンフィグモードでは、AI に「youtube://transcript/{videoId} の文字起こしを読んで」と頼むだけで済みます！

🟡 手動設定（全機能を解放）

MCP クライアント（例：Claude Desktop や Cursor）を手動で設定したい場合は、設定ファイルに以下を追加してください：

1. YouTube Data API v3 キーを取得（下記のセットアップ手順を参照）。
2. （強く推奨）無料の MongoDB 接続文字列を取得して、クォータを節約するキャッシュを有効化。

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_YOUTUBE_API_KEY_HERE",
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:[email protected]/youtube_niche_analysis"
      }
    }
  }
}

（Windows PowerShell ユーザーの方へ：npx が失敗する場合は、"command": "cmd" と "args": ["/k", "npx", "-y", "@kirbah/mcp-youtube"] を試してみてください）

次のステップ：スキルを追加する

サーバーが接続できたら、CreatorLens を試してみてください - これはこの MCP 専用に作られた Claude スキルで、生の YouTube データを 成長診断（弱いフック、パッケージング、ニッチへの迷い、フォーマットの転換）に変換します。

主な機能

• 最適化された動画情報： 高度なフィルターで動画を検索できます。詳細なメタデータ、統計情報（再生回数、いいねなど）、コンテンツの詳細を、トークン消費を最小限に抑えた構造で取得できます。
• 効率的な文字起こし管理： 多言語対応の動画キャプション/字幕を取得でき、LLM によるコンテンツ分析に最適です。
• 洞察に富むチャンネル分析： 簡潔なチャンネル統計（登録者数、再生回数、動画数）を取得し、データを肥大化させることなく、チャンネルのトップパフォーマンス動画を発見できます。
• 無駄のないトレンド発見： 地域とカテゴリ別に急上昇の動画を検索し、利用可能な動画カテゴリのリストを取得できます。AI による迅速な処理に最適化されています。
• AI 向けに構造化： すべてのレスポンスは、簡単に解析でき、言語モデルにとって即座に役立つように設計されています。
• 効率的なコメント取得： 動画のコメントを、結果数と返信数を細かく制御して取得できます。感情分析やフィードバック抽出に最適化されています。

利用可能なツール

このサーバーは以下の MCP ツールを提供しており、それぞれがトークン最適化されたデータを返すように設計されています：

ツール名	説明	パラメータ（詳細はツールスキーマを参照）
getVideoDetails	複数の YouTube 動画について、メタデータ、統計情報、エンゲージメント率、コンテンツ詳細を含む詳細かつ 簡潔な 情報を取得します。	videoIds（文字列の配列）
searchVideos	クエリ文字列に基づいて、さまざまなフィルタリングオプションを使用して動画またはチャンネルを検索し、簡潔な 結果を返します。	query（文字列）、maxResults（省略可能な数値）、order（省略可能）、type（省略可能）、channelId（省略可能）など
getTranscripts	複数の動画について、トークン効率の良い 文字起こし（キャプション）を取得します。全文または主要セグメント（イントロ／アウトロ）を選択できます。	videoIds（文字列の配列）、lang（省略可能な言語コードの文字列）、format（省略可能な列挙型: 'full_text'、'key_segments' — デフォルトは 'key_segments'）
getChannelStatistics	複数のチャンネルについて、簡潔な 統計情報（登録者数、視聴回数、動画数、作成日）を取得します。	channelIds（文字列の配列）
getChannelTopVideos	チャンネルの最もパフォーマンスの高い動画の一覧を、簡潔な 詳細とエンゲージメント率とともに取得します。	channelId（文字列）、maxResults（省略可能な数値）
getTrendingVideos	指定した地域と省略可能なカテゴリの急上昇動画の一覧を、簡潔な 詳細とエンゲージメント率とともに取得します。	regionCode（省略可能な文字列）、categoryId（省略可能な文字列）、maxResults（省略可能な数値）
getVideoCategories	特定の地域で利用可能な YouTube 動画カテゴリ（ID とタイトル）を取得し、必要最小限のデータのみ を提供します。	regionCode（省略可能な文字列）
getVideoComments	YouTube 動画のコメントを取得します。並べ替え、結果の制限、各コメントに対する少数の返信の取得が可能です。	videoId（文字列）、maxResults（省略可能な数値）、order（省略可能）、maxReplies（省略可能な数値）、commentDetail（省略可能な文字列）
findConsistentOutlierChannels	特定のニッチ内で一貫して外れ値としてパフォーマンスするチャンネルを特定します。MongoDB 接続が必要です。	niche（文字列）、minVideos（省略可能な数値）、maxChannels（省略可能な数値）

詳細な入力パラメータとその説明については、src/tools/ ディレクトリ内の各ツールの設定ファイル（例: src/tools/video/getVideoDetails.ts）にある inputSchema を参照してください。

API クォータコストに関する注意: ほとんどのツールは非常に効率的です。getVideoDetails、getChannelStatistics、getTrendingVideos は 1 回の呼び出しにつきわずか 1 ユニット しか消費しません。getTranscripts ツールの API コストは 0 です。新しい getVideoComments ツールには変動コストがあります。基本呼び出しは 1 ユニット ですが、返信をリクエストする場合（maxReplies > 0 を設定）、返信を取得するトップレベルのコメントごとに 追加で 1 ユニット かかります。検索ベースのツールが最も高コストです。searchVideos は 100 ユニット、getChannelTopVideos は 101 ユニット です。

高度な使用方法とローカル開発

コントリビュートしたい場合、サーバーを変更したい場合、または MCP クライアントの管理環境の外でローカルに実行したい場合:

前提条件

• Node.js（バージョンは package.json の engines フィールドで指定 - 現在は >=22.0.0）
• npm（通常は Node.js に付属しています）
• YouTube Data API v3 キー（YouTube API セットアップを参照）

ローカルセットアップ

1. リポジトリをクローンします:

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

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

   npm ci
   

3. 環境を構成します: .env.example をコピーして、ルートに .env ファイルを作成します:

   cp .env.example .env
   

   次に、.env を編集して YOUTUBE_API_KEY を追加します:

   YOUTUBE_API_KEY=your_youtube_api_key_here
   MDB_MCP_CONNECTION_STRING=your_mongodb_connection_string_here
   

開発スクリプト

# Run in development mode with live reloading
npm run dev

# Build for production
npm run build

# Run the production build (after npm run build)
npm start

# Lint files
npm run lint

# Run tests
npm run test
npm run test -- --coverage # To generate coverage reports

# Inspect MCP server using the Model Context Protocol Inspector
npm run inspector

MCP クライアントを使用したローカル開発

MCP クライアントに_ローカル開発バージョン_を実行させるには（公開されている NPM パッケージの代わりに）:

1. package.json に、ウォッチしない起動用のスクリプトがあることを確認します。例:

   "scripts": {
     "start:client": "tsx ./src/index.ts"
   }
   

2. MCP クライアントを構成して、このローカルスクリプトを起動します:

   {
     "mcpServers": {
       "youtube_local_dev": {
         "command": "npm",
         "args": ["run", "start:client"],
         "working_directory": "/absolute/path/to/your/cloned/mcp-youtube",
         "env": {
           "YOUTUBE_API_KEY": "YOUR_LOCAL_DEV_API_KEY_HERE"
         }
       }
     }
   }
   

   上記の env ブロックに関する注意: クライアント構成の env ブロックに YOUTUBE_API_KEY を直接設定することは、API キーを提供する 1 つの方法です。あるいは、サーバーが working_directory に基づいて .env ファイルを正しく読み込む場合、プロジェクトルートのローカル .env ファイルに YOUTUBE_API_KEY が含まれていれば、クライアントの env ブロックで指定する必要はないかもしれません。サーバーが .env ファイルを見つけるには、working_directory のパスが絶対パスで正確である必要があります。

YouTube API セットアップ

1. Google Cloud Console に移動します。
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
3. ナビゲーションメニューで、「APIs & Services」>「Library」に移動します。
4. 「YouTube Data API v3」を検索し、プロジェクトで有効化します。
5. 「APIs & Services」>「Credentials」に移動します。
6. 「+ CREATE CREDENTIALS」をクリックし、「API key」を選択します。
7. 生成された API キーをコピーします。これが YOUTUBE_API_KEY です。
8. 重要なセキュリティ手順: 不正使用を防ぐために API キーを制限します。API キー名をクリックし、「API restrictions」で「Restrict key」を選択して「YouTube Data API v3」を選びます。該当する場合は「Application restrictions」（例: IP アドレス）を追加することもできます。

システム要件

• Node.js: >=22.0.0（package.json で指定）
• npm（依存関係の管理とスクリプトの実行用）

詳細解説: findConsistentOutlierChannels ツール

findConsistentOutlierChannels ツールは、特定のニッチにおいて、その規模を一貫して上回るパフォーマンスを示す、新興または確立された YouTube チャンネルを特定するために設計されています。このツールは、高い可能性を秘めたチャンネルを探しているコンテンツクリエイター、マーケター、アナリストにとって特に役立ちます。

重要な注意: このツールは、チャンネルデータを保存および分析するために MongoDB 接続が必要です。MDB_MCP_CONNECTION_STRING が設定されていない場合、このツールは利用できません。

内部ロジックの概要

このツールは、YouTube Data API と MongoDB データベースの両方を活用し、多段階の分析プロセスを通じて動作します。

1. 候補の検索 (フェーズ 1):

   • 指定された query を使用して、YouTube 上で関連する動画やチャンネルを検索します。
   • 指定されている場合は、videoCategoryId と regionCode に基づいて初期結果をフィルタリングします。
   • より詳細な分析のために、潜在的なチャンネルを幅広く収集します。

2. チャンネルのフィルタリング (フェーズ 2):

   • 候補チャンネルの詳細な統計情報 (登録者数、総再生回数、動画数) を取得します。
   • channelAge (例: 6 か月未満のチャンネルは「NEW」、6～24 か月は「ESTABLISHED」) に基づいてチャンネルをフィルタリングします。
   • 一貫性の検討対象として、チャンネルが最小動画数を満たしていることを確認します。

3. 詳細分析 (フェーズ 3):

   • フィルタリングされた各チャンネルについて、最近のトップパフォーマンス動画を取得します。
   • 各動画の「バイラル係数」(例: 登録者数に対する再生回数) を計算します。
   • consistencyLevel (例: 動画の約 30% が外れ値のパフォーマンスを示す場合は「MODERATE」、約 50% の場合は「HIGH」) を評価します。
   • outlierMagnitude (例: 再生回数が登録者数を上回る場合は「STANDARD」、再生回数が登録者数の 3 倍を超える場合は「STRONG」) を判定します。

4. ランキングとフォーマット (フェーズ 4):

   • ニッチ内での一貫性、外れ値の大きさ、および全体的なパフォーマンスに基づいてチャンネルをランク付けします。
   • 主要なチャンネル指標や外れ値動画の例を含め、LLM に適したトークン最適化された構造に結果をフォーマットします。

フローを制御する主要なパラメータ

このツールの動作は、主に以下のパラメータによって制御されます。

• query (string, 必須): 分析する中心的なトピックまたはニッチ (例: 「DIY 住宅修理」、「量子コンピューティング解説」)。
• channelAge (enum: "NEW", "ESTABLISHED", デフォルト: "NEW"): 検索を新興チャンネルまたはより成熟したチャンネルに絞り込みます。
• consistencyLevel (enum: "MODERATE", "HIGH", デフォルト: "MODERATE"): チャンネルの動画が外れ値としてどの程度一貫してパフォーマンスを発揮する必要があるかのしきい値を設定します。
• outlierMagnitude (enum: "STANDARD", "STRONG", デフォルト: "STANDARD"): 「外れ値」と見なされるために、動画のパフォーマンスが典型的な期待値 (例: 再生回数と登録者数) をどの程度大幅に上回る必要があるかを定義します。
• videoCategoryId (string, 任意): 検索を特定の YouTube カテゴリ ID に絞り込みます。
• regionCode (string, 任意): 特定の地理的地域に関連するチャンネルを対象とします。
• maxResults (number, デフォルト: 10): 返されるトップ外れ値チャンネルの数を制限します。

セキュリティに関する考慮事項

• API キーのセキュリティ: YOUTUBE_API_KEY は機密情報です。リポジトリに直接コミットしないでください。環境変数 (例: .gitignore に記載する必要がある .env ファイル経由) を使用してください。
• API クォータ: YouTube Data API には 1 日あたりの使用クォータがあります (デフォルトは 10,000 ユニット)。すべてのツール呼び出しはこのクォータを消費します。Google Cloud Console で使用状況を監視し、各ツールのコストに注意してください。API メソッドごとのコストの詳細な内訳については、公式ドキュメント を参照してください。
• 入力検証: サーバーはすべてのツールパラメータに対して Zod を使用した堅牢な入力検証を行い、セキュリティと信頼性を向上させています。

ライセンス

このプロジェクトは MIT ライセンス の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。