# youtube-mcp

`@ザビエル-zav` のYouTubeチャンネル分析を、Claudeから直接できるようにするMCPサーバー。
「先週の動画、どれが一番CTR良かった?」のような質問に、実データを取ってきて答えられる状態を目指す。

Node.js製(Python不使用)。YouTube Analytics API / Reporting API / Data API v3 を
公式のNode用ライブラリ(`googleapis`, `google-auth-library`)でラップし、
MCP公式のTypeScript SDK(`@modelcontextprotocol/sdk`)でツールとして公開している。

## 使うAPIと使い分け

| 欲しいデータ | API | 取得方式 |
|---|---|---|
| 再生数、視聴時間、平均視聴維持率、登録者増減、流入元、視聴者層 | YouTube Analytics API | リクエストするとその場でJSONが返る |
| サムネ表示回数、インプレッションCTR | YouTube Reporting API (Bulk Reports) | 事前にジョブ登録 → 毎日CSVが生成 → DLして読む |
| 動画タイトル、説明、コメント | YouTube Data API v3 | リクエストするとその場でJSONが返る |

CTRだけ取得方式が根本的に違う(バルクレポート)ため、`register-reach-job.js` で
ジョブ登録 → `download-reports.js` で定期的にローカルへCSVを蓄積、という別経路になっている。

## セットアップ

### 1. Google Cloud Console

1. プロジェクトを作成
2. 以下3つのAPIを有効化
   - YouTube Analytics API
   - YouTube Reporting API
   - YouTube Data API v3
3. OAuth同意画面を設定(ユーザーの種類=外部、テストユーザーに自分のGoogleアカウントを追加)
4. 認証情報 > OAuthクライアントID > アプリの種類=デスクトップアプリ を作成し、JSONをダウンロード
5. ダウンロードしたJSONを `client_secret.json` という名前でこのリポジトリ直下に置く

   **`client_secret.json` と、初回認証後に作られる `token.json` は絶対にコミットしないこと。**
   `.gitignore` 済みだが、誤って `git add -f` しないよう注意。

### 2. Node.jsと依存パッケージ

Node.js 18以上が必要(未インストールなら [nodejs.org](https://nodejs.org/) からLTS版を入れる。
インストーラーに `npm` も含まれるので、Pythonのような別途PATH設定は基本不要)。

```bash
npm install
```

### 3. リーチレポート(CTR)のジョブ登録 — 最優先で実行

Reporting API は「ジョブを登録した日」からデータ生成が始まり、過去分も登録時点から
30日前までしか遡れない。**登録が遅れるほど過去のCTRデータが失われる**ので、
他の作業より先にこれだけ実行しておく。

```bash
npm run register-reach-job
```

初回はブラウザが開いて認証を求められる(以降は `token.json` で自動更新)。

### 4. MCPサーバー起動

```bash
npm start
```

Claude Desktop から使う場合は `claude_desktop_config.json` に以下のように登録する。

```json
{
  "mcpServers": {
    "youtube-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-mcp/server.js"]
    }
  }
}
```

### 5. リーチレポートのダウンロード(登録から数時間〜2日後)

```bash
npm run download-reports
```

`data/reach/<report_type>/` 配下にCSVが蓄積される。レポートはYouTube側で60日
(過去データ分は30日)で消えるため、**定期的に(できれば1日1回)実行し続ける**こと。
Windowsならタスクスケジューラ、Mac/Linuxならcronに登録しておくとよい。
`get_reach` ツールはこのローカルCSVを読む。

## 公開ツール一覧

| ツール名 | 引数 | 返すもの |
|---|---|---|
| `get_channel_summary` | `start_date`, `end_date` | 期間全体の再生数・視聴時間・登録者増減 |
| `list_top_videos` | `start_date`, `end_date`, `limit` | 再生数上位の動画とその基本数値 |
| `get_video_stats` | `video_id`, `start_date`, `end_date` | 指定動画の詳細数値 |
| `get_retention_curve` | `video_id`, `start_date`(省略可), `end_date`(省略可) | 視聴維持率カーブ(10%刻み)+最大離脱ポイント |
| `get_traffic_sources` | `video_id` または `start_date`+`end_date` | 流入元の内訳 |
| `get_reach` | `start_date`, `end_date` | サムネ表示回数とCTR(ローカル蓄積CSVから集計) |
| `get_comments` | `video_id`, `limit` | コメント一覧(関連度順) |

出力は生JSONではなく、丸めた数値・上限20件程度のテキスト表で返す
(Claude側のコンテキスト消費を抑えるため)。

## 既知の制約

- Analytics APIのデータは YouTube Studio 表示より最大2日程度のラグがある。「昨日の数字」は取れないことがある。
- `get_reach` はローカルにダウンロード済みのCSVしか見ない。`download-reports.js` を実行していない期間のデータは出てこない。
- `channel_reach_basic_a1` / `channel_reach_combined_a1` の正確な列構成は未確認。`get_reach` は列名をキーワードで推測して読むフォールバックにしてあるが、実際にダウンロードしたCSVのヘッダーで一度確認すること。
- 書き込み系スコープは付けていない(読み取り専用)。動画を誤って変更・削除する経路は存在しない。

## デプロイ先の分岐

| 使いたい場所 | 必要なもの |
|---|---|
| Claude Desktop アプリ | ローカルで `npm start`(stdio)を起動するだけでOK |
| claude.ai (Web/スマホ) | HTTPSでアクセスできるリモートMCPサーバーとして公開が必要 |

スマホからも使いたい場合は、`StdioServerTransport` を `StreamableHTTPServerTransport`
(`@modelcontextprotocol/sdk/server/streamableHttp.js`)に切り替えて、
既存のホスティング環境に相乗りするのが早い。