youtube-analytics-mcp

所有するチャンネル（複数チャンネルも可）のYouTube Analytics、Data v3、Reporting APIの全機能をAIアシスタントに提供するMCPサーバーです。

ほとんどのYouTube MCPサーバーは少数のメトリクス文字列をハードコードしているため、プリセットリストにない質問にはフォークしない限り答えられません。このサーバーはその逆の設計です:youtube_analytics_query は reports.query が受け付けるすべてのパラメータを取り、youtube_data_call / youtube_reporting_call も他の2つのAPIについて同様です。プリセットはその上にある便利機能であり、何かを実現する唯一の経路ではありません。

Google Cloud の OAuth クライアントはご自身で用意してください。このパッケージには何も同梱されておらず、認証情報が第三者を経由することもなく、すべて stdio 上でローカルに実行されます。

ツール

すべてのデータツールはオプションの account を受け取るため、1つの会話で2つのチャンネルを比較できます。

大きな結果はモデルを経由せずファイルに出力

youtube_analytics_query、youtube_data_call、youtube_reporting_call は outputPath(およびオプションの format:csv または json。指定がなければ拡張子から推測)を受け取ります。これを指定すると、完全な結果がディスクに書き込まれ、要約(行数、列数、バイトサイズ、最初の3行)だけが返ります。指定しない場合、100行を超える結果は切り詰められ、このオプションへのポインタが付けられます。1000行のレポートをインラインで返すと、呼び出し元のコンテキストウィンドウを消費し、到着時には読めないものになるからです。

本当に大量の作業(全動画の毎日、数か月分)には、youtube_reporting_call を通じて Reporting API を使用してください。これはダウンロード可能な日次 CSV レポートを生成し、reports.query が1回の呼び出しでは返さない次元の組み合わせを提供します。

Related MCP server: YouTube MCP Server

セットアップ

1. Google Cloud の OAuth クライアントを一度作成

• プロジェクトを作成または選択します。

• API とサービス → ライブラリ: YouTube Analytics API、YouTube Data API v3、YouTube Reporting API を有効にします。

• OAuth 同意画面 → 対象者: ユーザータイプを 外部 に設定します(内部は Workspace 組織が接続されている場合のみ選択可能です)。同じ 対象者ページ の テストユーザー で、+ ユーザーを追加 をクリックし、各チャンネル所有者の Google アカウントを追加します — ご自身のアカウントも含めて。

  これを逃すと、同意は 「… は Google の認証プロセスを完了していません。アプリは現在テスト中であり、開発者が承認したテスターのみがアクセスできます。」 というエラーで失敗します。プロジェクト所有者であってもテストユーザーにはなりません。明示的に自分を追加する必要があります。

• 公開ステータスを [本番] に設定 します。これは見た目以上に重要です。Google によると:

  外部ユーザータイプ用に構成された OAuth 同意画面と公開ステータスが「テスト」の Google Cloud Platform プロジェクトには、リフレッシュトークンが発行され、7日で期限切れになります。ただし、要求される OAuth スコープが名前、メールアドレス、ユーザープロファイルのサブセットのみの場合を除きます。

  すべての YouTube スコープは機密情報であるため、テスト アプリでは毎週再承認が必要になります。

  これらのスコープでは公開が単なるスイッチではないことに注意してください。コンソールはデモ動画を要求し、Testing を離れる前に YouTube API の認証レビューをアプリに通す必要がある可能性が高いです。これは個人用ツールとしては現実的な作業であり、毎週の再同意の方が良いトレードオフであることが多いです。代替案については、下の 7日間の付与制限 を参照してください。

• 認証情報 → 認証情報を作成 → OAuth クライアント ID → デスクトップ アプリ。ウェブ アプリケーション ではありません:このサーバーは実行のたびにランダムな空きループバックポートをリッスンし、Web クライアントではポートを含むすべてのリダイレクト URI を事前に登録する必要があります。

• JSON をダウンロードします。

2. サーバーにクライアントの場所を伝える

設定ファイルに配置します(config.example.json を参照):

// %APPDATA%\youtube-analytics-mcp\config.json          (Windows)
// ~/Library/Application Support/youtube-analytics-mcp/  (macOS)
// ~/.config/youtube-analytics-mcp/config.json           (Linux)
{
  "client": { "client_id": "...", "client_secret": "..." }
}

youtube-analytics-mcp --where を実行すると、そのディレクトリが表示されます。環境変数も機能し、優先されます — YTMCP_CLIENT_ID + YTMCP_CLIENT_SECRET、または Google のダウンロードをそのまま指す YTMCP_CLIENT_FILE({"installed": …} のラッパーは自動的に展開されます)。YTMCP_CONFIG_DIR でディレクトリ全体を移動できます。

3. 各チャンネルを承認

bun run auth                      # or: youtube-analytics-mcp --authorize
bun run auth -- --alias second    # name it yourself

ブラウザーが同意ページで自動的に開きます。URL も印刷されます。ブラウザーを開けない場合(SSH、コンテナ、CI)に備えてです。チャンネルを所有する Google アカウントを選択して承認します。チャンネルごとに繰り返します — ブラウザーで毎回異なるアカウントを選択 してください。アカウントは --alias を渡さない限り、@handle にちなんで名前が付けられます。

ブラウザーを起動しないようにするには YTMCP_NO_BROWSER=1 を設定するか、1回の呼び出しのために youtube_authorize ツールに openBrowser: false を渡します。

リフレッシュトークンは同じディレクトリの accounts.json に書き込まれ、手動で編集する config.json とは別です。バグレポートに貼り付ける可能性のあるファイルにトークンが含まれることはありません。両方とも、プラットフォームが対応している場合は 0600 で書き込まれます。

アシスタントがこれを操作することもできます。youtube_authorize は同意 URL を即座に返し、バックグラウンドでリスニングを続けます。youtube_authorize_status はその結果を報告します。これはブロックしません。同意には人間の時間がかかり、MCP クライアントはそのずっと前にツール呼び出しを放棄するからです。URL は設定ディレクトリの pending-auth.txt にも書き込まれます。ほとんどのクライアントはサーバーの stderr を破棄し、誰も読めない URL は役に立たないからです。

4. MCP クライアントに登録

Claude Code:

claude mcp add youtube-analytics --scope user -- bunx youtube-analytics-mcp

または手動で、任意のクライアントの mcpServers マップに:

{
  "mcpServers": {
    "youtube-analytics": { "command": "bunx", "args": ["youtube-analytics-mcp"] }
  }
}

デフォルトで読み取り専用

動画の更新、コメントの投稿やモデレーション、サムネイルのアップロードはライブチャンネルでは元に戻せないため、書き込みスコープは要求されず、非 GET 呼び出しは拒否されます。有効にするには YTMCP_ALLOW_WRITE=1 を設定し、再承認 してください — フラグだけでは何も起こりません。保存されたトークンにスコープが含まれていないためです。

同時視聴者数と、誰も推測しないクエリ形状

averageConcurrentViewers と peakConcurrentViewers は終了したライブ配信で機能し、Studio 自身の数値と正確に一致します。これらは、API が1つの形状以外で拒否するため、存在しないと広く信じられています:フィルタは単一の動画に固定しかつ dimensions を livestreamPosition にする必要があります。

エラーは欠落している次元を名前指定せず、特に 500 はリクエストが間違っているのではなくメトリクスが壊れているように見えます。youtube_concurrent_curve はこれを組み立てて、ピーク、平均、分単位の曲線全体を返します。

実際には取得できないもの

youtube_capabilities が現在のリストを返します。どちらも、メトリクスを要求して Unknown identifier が返ることを確認しました。これは、API が聞いたことのない名前と、知っているがここでは提供できない名前を区別する方法です。

• ライブチャットのメッセージとリアクションの合計。 Studio のみ。liveChatMessages はチャットをリアルタイムで読み取るもので、終了したチャットは復元できません。

• インプレッションとインプレッションクリック率。 Studio のみ、リーチタブにあります。

知っておくべき2つのこと

「公開日からの」ウィンドウはありません。 Analytics API は純粋に日付範囲のみを扱うため、配信日を含むウィンドウは、構成上、その配信のライブ視聴者を返します。Studio のデフォルトの動画ごとのウィンドウはライブ期間全体を除外するため、ライブ配信を分析する際に簡単で高くつく罠になります。この API はその罠に陥ることはありません。

Analytics のクォータは別です。 Analytics と Reporting API は Data API v3 の日次ユニット予算とは独立して測定されるため、ここでのクエリはライブチャットのポーリングが競合するクォータを消費しません。これらが別々の API で、それぞれ独自のコンソールクォータページを持つことからの強い推測であり、測定されたものではありません。

開発

bun install
bun run dev          # start on stdio
bunx tsc --noEmit    # typecheck
bun run inspector    # MCP Inspector

MIT。

API は数日遅れます

確定された Analytics データはすぐには利用できません。2026-08-25 に測定したところ、日次ディメンションの行は 08-22 まで実行され、そこで停止しました。過去3日間のセッションは、ゼロ行ではなく、行がまったく返されませんでした。数時間前に終了した配信のクエリは、トラフィックのないチャンネルのように見えます。

Studio のウェブ UI には API が公開していないリアルタイムパスがあるため、当日のレポートは依然として Studio から取得する必要があります。このサーバーは、およそ3日より古いものすべてに使用してください。そこでは、Studio を1動画ずつクリックするよりもはるかに優れています。

7日間の付与制限と、なぜコードで回避できないのか

Cloud プロジェクトの公開ステータスがテストで外部ユーザータイプの場合、Google は要求されるスコープが名前、メール、プロフィールのみでない限り、7日後にリフレッシュトークンを失効させます。すべての YouTube スコープは機密情報であるため、この例外はここでは決して適用されません。

これは自動化では回避できません。 7日間はリフレッシュトークンに適用されます。新しいトークンを発行するには、人間がブラウザーで同意画面を承認する必要があります — それが同意の意味であり、回避すべきギャップではありません。アクセストークンのリフレッシュ頻度を上げても影響はありません。

代わりにこのサーバーが行うこと:

• youtube_accounts は各付与の ageDays を報告し、5日目から警告します。

• 期限切れの付与は、裸の invalid_grant ではなく、原因と修正を名前指定したメッセージで失敗します。

• youtube_refresh_tokens(または CLI からの --refresh)は、すべての付与をヘルスチェックとして実行します。これは保険でもあります:7日間の時計が発行から絶対なのか、使用によってスライドするのかは確立されていません。スライドする場合、スケジューラーで毎日実行すると付与を無期限に維持できます。スライドしない場合でも、呼び出しコストはほとんどかかりません。どちらにしても実行する価値があります。

• 再同意は youtube_authorize への1回の呼び出しで、ブラウザーを自動的に開きます — 約15秒です。

本当の修正は、コスト順に:

1. 公開ステータス → 本番環境。 無料で、許可が期限切れにならなくなります。機密性の高い YouTube スコープの場合、Google は公開を許可する前にデモ動画と審査を要求することがあり、個人用ツールとしてはかなりの作業になります。

2. 内部ユーザータイプ。 7日間の制限も審査もありませんが、このオプションはプロジェクトが Google Workspace 組織に属している場合にのみ存在します — 有料サブスクリプションです。

3. 毎週の再同意付きで公開。 単一ユーザーツールの場合、これが正解であることが多いです。