youtube-analytics-mcp

ローカルで動作する読み取り専用のMCPサーバーで、ClaudeにあなたのYouTubeチャンネルの非公開Analyticsデータ（再生回数、再生時間、維持率、登録者数、トラフィックソース、視聴者層、収益、サムネイル表示回数/CTR）へのアクセスを提供します。公開APIキーだけで見られるものではありません。

このサーバーは、チャンネル上の何かを編集・アップロード・公開・削除することは一切できません。完全なセキュリティレビューは SECURITY.md を参照してください。

必要条件

• Node.js 22+

• データを取得したいYouTubeチャンネルを所有（または管理）しているGoogleアカウント

• macOS、Linux、またはWSL（npm run auth のブラウザフローは open コマンドを使用）

Related MCP server: YouTube MCP Server

セットアップ手順

以下の順序で実行してください。手順1〜4はGoogle Cloud Consoleで、手順5〜8はお使いのマシンで行います。

1. Google Cloudプロジェクトを作成する

console.cloud.google.com にアクセスし、新しいプロジェクトを作成します（または既存の使い慣れたプロジェクトを選択）。

2. 3つのAPIを有効にする

プロジェクトで、APIとサービス → ライブラリ に移動し、以下をそれぞれ有効にします：

• YouTube Data API v3

• YouTube Analytics API

• YouTube Reporting API（サムネイルのインプレッション/CTRにのみ必要 — 下記 を参照）

3. OAuth同意画面を設定する

APIとサービス → OAuth同意画面 に移動します。

• ユーザーの種類: 外部（Google Workspace アカウントをお持ちの場合は内部も可）

• 必要なアプリ名・サポートメールアドレス欄を入力

• 求められたらスコープを追加（アプリが直接要求するため、この画面は存在すれば十分です）

• アプリを公開（本番）に設定する。 ここでつまずく人が多いステップです。テストモードのアプリは、明示的にテストユーザーとして追加したアカウントからのみサインインでき、さらにリフレッシュトークンは7日で失効するため、毎週ステップ6をやり直すことになります。本番公開（Googleの審査提出なし）は個人ツールには問題ありません — サインイン時に「未確認アプリ」の警告が表示されますが、詳細 → [アプリ名] に移動（安全ではない） をクリックして続行してください。これは自分のアプリでは想定どおりで安全です。

4. OAuth認証情報を作成する

APIとサービス → 認証情報 → 認証情報を作成 → OAuthクライアントID に移動します。

• アプリケーションの種類: デスクトップアプリ

• 任意の名前を付ける

• クライアントID と クライアントシークレット をコピー — 手順5で必要になります

ここでリダイレクトURIを登録する必要はありません。このサーバーは認証時に一時的なローカルポートをバインドし、Googleはデスクトップ型クライアントに対して任意のloopbackアドレスを受け入れます。

5. インストールとビルド

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. 認証情報の設定

cp .env.example .env

.env を編集し、手順4で取得したClient ID / Client Secretを貼り付けます：

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env はgitignoreされているため、コミットされることはありません。オプション設定:

• GOOGLE_API_KEY — 現在のツールでは不要です。サーバーを自分で拡張しない限り設定は不要です。

• REVENUE_CURRENCY — デフォルトは USD。AdSenseの通貨（例：BRL）で表示したい場合は設定してください。Google側でサーバーサイド変換されます。

7. 認証

npm run auth

ブラウザが開いてGoogleアカウントでログインし、リフレッシュトークンが ~/.youtube-analytics-mcp/token.json に保存されます（アクセス権限はユーザーのみに制限され、リポジトリには保存されません）。この操作は一度だけでOKです。以降はサーバーが自動的にアクセストークンを更新します。

動作確認：

npm run auth:status

Authenticated とチャンネル名が表示されれば成功です。

8. Claude Codeに設定する

MCP設定ファイルに、このプロジェクトの dist/index.js への絶対パスを指定して追加します：

{
  "mcpServers": {
    "youtube-analytics-channel": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-analytics-mcp/dist/index.js"]
    }
  }
}

Claudeを再起動（またはMCPサーバーをリロード）すると、以下のツールが使えるようになります。

利用可能なツール

インプレッションとCTRに関する注意

サムネイルのインプレッション数とCTR（クリック率）は、インタラクティブAPI（reports.query）ではどのディメンション/フィルターの組み合わせでも公開されていません。これはドキュメントからの推測ではなく、実際に検証済みです。このデータはYouTubeのバルク「リーチレポート」という別の非同期ジョブAPIでのみ取得できます：

1. get_impressions_and_ctr を初回呼び出しすると、Googleにリーチレポートのジョブが登録されます。

2. Googleが最初のレポートを生成するまでに24〜48時間かかり、その後はほぼ毎日新しいレポートが生成されます。

3. 以降、get_impressions_and_ctr（またはインプレッション/CTRでの並び替えを含む get_top_videos）を呼び出すたびに、新しいレポートをローカルキャッシュ（~/.youtube-analytics-mcp/reach-cache.json）に同期してから、そのキャッシュから回答します。

最初のレポートが生成されるまでは、impressions: 0、impressionsCtr: null、およびその理由を説明する note が返されます。これは想定どおりの動作であり、バグではありません。

トラブルシューティング

• npm run auth で「アクセスがブロックされました」: OAuth同意画面がまだ「テスト」モードです。手順3に戻り、アカウントをテストユーザーに追加するか、本番環境に公開してください。

• NotAuthenticatedError が発生: npm run auth を実行してください。

• 収益が常に 0: チャンネルが収益化されていないか、その期間の数値が本当にゼロの可能性があります。このツールは収益を捏造しません — 実際の権限/アクセスエラーかどうかは get_revenue_analytics の available フィールドで確認してください。

• get_impressions_and_ctr / インプレッション/CTRでソートした get_top_videos が何も返さない: レスポンスの dataCoverage を確認してください。earliestDate が null の場合、レポートジョブがまだ最初のレポートを生成していません（初回呼び出しから最大24〜48時間かかります）。

テスト

npm test

セキュリティ

SECURITY.md に完全なセキュリティレビュー（OWASP Top 10含む）があります。要約：すべてのシークレットはあなたのマシン上、リポジトリ外にのみ保存され、Google APIへのリクエストはすべて検証済みです。

ライセンス

MIT