YouTube MCP Server

Claude Desktop、Claude Code、Codex などの MCP クライアントから YouTube を利用するためのオープンソースの Model Context Protocol (MCP) サーバー。

主なワークフローは次のとおりです。

1. MCP クライアントに曲のリストを与える。

2. 何かを変更する前に、ランク付けされた YouTube の一致結果を確認する。

3. 選択した動画から非公開のプレイリストを作成する。

サーバーはまた、YouTube の検索や、動画、チャンネル、プレイリスト、コメントの読み取りのための、クォータを意識したツールも提供します。

[!IMPORTANT] TypeScript パッケージ、stdio サーバー、公開・認証付き読み取り、PKCE OAuth、音楽準備、確認済みの新規プレイリスト作成、およびプレビュー済みのプレイリスト変更は実装済みでテスト済みです。準備した音楽ドラフトを既存のプレイリストに直接追加することは依然として計画中です。現時点では、曲を挿入できるのはプレイリスト作成時のみです。

設計目標

• コミット前プレビューのセマンティクスによる安全なプレイリスト書き込み。

• 公式の YouTube Data API v3 エンドポイントのみを使用。

• Google OAuth クライアントは各自で用意。このプロジェクトが共有の Google 認証情報を同梱することはありません。

• シークレットは可能な限り OS のキーチェーンに保存。

• 予測可能なクォータ使用、ページネーション、キャッシュ、リトライ、正規化されたエラー。

• 簡単なインストールと小さな攻撃面のためのローカル stdio トランスポート。

• YouTube のコンテンツを信頼できないデータとして扱う、構造化され境界のあるツール出力。

• Node.js 20.17 以降でのクロスプラットフォーム TypeScript サポート。

計画されている v1 の範囲

読み取りツール

• 動画、チャンネル、プレイリストを検索。

• 動画、チャンネル、プレイリスト、コメントのデータを読み取り。

• 認証済みユーザーのチャンネル、アップロード、プレイリストを読み取り。

• 明示的でステートレスなページネーションのためのプロバイダーのページトークンを返す。

音楽プレイリストのワークフロー

• 準備リクエストごとに最大 50 件の構造化トラックを受け付ける。

• 有力な YouTube ミュージックビデオの一致候補を検索してランク付けする。

• 弱い一致を黙って選ぶのではなく、あいまいさと代替案を表示する。

• 明示的に選択された一致を新しいプレイリストにコミットする。既存プレイリストへのコミットは計画中。

• 新しいプレイリストはデフォルトで private にする。

プレイリスト管理

• プレイリストを作成し、動画を追加する。

• プレイリストのメタデータやプライバシーを更新する。

• プレイリストの項目を並べ替えたり削除したりする。

• 短期間有効な一度きりの確認ハンドルが発行された後にプレイリストを削除する。

プレイリストの更新、項目の削除・並べ替え、削除は 2 つのツールを使用します。youtube_prepare_playlist_mutation は書き込みを行わずに正確な差分と 10 分間有効なハンドルを返し、youtube_apply_playlist_mutation はそのハンドルを一度だけ消費する前に、所有権とプレイリストのスナップショットを再確認します。

プレイリスト管理以外の書き込み（アップロード、コメント、評価、登録、チャンネル変更）は、意図的にスコープ外です。

セットアップ

npm パッケージはまだ公開されていないため、サーバーはクローンからビルドして実行します。手順を順番に進めてください。

ステップ 1 — Node.js と npm を確認する

node -v
npm -v

node -v が v20.17 以降を表示し、npm -v がバージョンを表示する場合は、ステップ 3 に進んでください。どちらかのコマンドが「command not found」と表示した場合は、ステップ 2 に進んでください。

ステップ 2 — Node.js と npm をインストールする（ステップ 1 が失敗した場合のみ）

npm は Node.js に同梱されています。Node をインストールすると両方がインストールされます。お使いのプラットフォームに合った行を選び、ステップ 1 を再実行して確認してください。

Node をシステム全体にインストールしたくない場合や、複数の Node バージョンを並行して使う必要がある場合は、バージョンマネージャーを使用してください。

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

Windows の場合の同等品は nvm-windows です。nvm install 22 を実行してから nvm use 22 を実行します。

インストール後、ターミナルを閉じて開き直し、node -v と npm -v を再実行してください。

ステップ 3 — 依存関係をインストールしてビルドする

git clone <repository-url>
cd "Youtube MCP"
npm ci
npm run build

npm ci は package-lock.json に記録された正確なバージョンをインストールします。依存関係を変更する意図がある場合にのみ npm install を使用してください。ビルドは実行可能ファイルを dist/cli/index.js に書き出します。以降のすべてのコマンドはこれを呼び出します。

ビルドとローカルデータディレクトリを確認します。

node dist/cli/index.js doctor

ステップ 4 — Google 認証情報を作成する

以下のすべてはご自身の Google Cloud プロジェクトから取得します。このプロジェクトが共有の Google 認証情報を同梱することはありません。

1. Google Cloud コンソール でプロジェクトを作成または選択します。

2. そのプロジェクトで YouTube Data API v3 を有効にします。

3. API キー を作成します（認証情報 → 認証情報を作成 → API キー）。これは公開読み取りをカバーします。

4. OAuth 同意画面 を構成します。プロジェクトが「テスト中」ステータスの間は、テストユーザー に自分の Google アカウントを追加してください。そうしないと login が拒否されます。

5. 種類が デスクトップアプリ の OAuth クライアント を作成し、クライアント ID と クライアントシークレット の両方をコピーします。

Google は、インストール型アプリケーションであっても認可コード交換で client_secret を要求します。そのため、ここでは PKCE はシークレットを置き換えるのではなく補完します。

ステップ 5 — サーバーが必要とする認証情報

認証情報は全部で 4 つあります。最初の 3 つはあなたが用意し、4 つ目は login が取得します。

オプションの環境変数: YOUTUBE_MCP_PROFILE（デフォルトは default）、YOUTUBE_MCP_DATA_DIR、YOUTUBE_MCP_LOG_LEVEL（error、warn、info、debug）。.env.example を参照してください。

これらをチャットメッセージ、共有の MCP 設定ファイル、またはコミットされるコマンドに貼り付けないでください。対話型プロンプトか、クライアントの環境変数・シークレット注入フィールドを使用してください。

ステップ 6 — setup を実行してからログインする

これらを順番に実行してください。setup はプロファイルに保存されたスコープとチャンネル ID を書き換えるため、login の 後 に実行するとその状態が破棄され、再度ログインする必要があります。

macOS と Linux:

YOUTUBE_OAUTH_CLIENT_ID="YOUR_DESKTOP_CLIENT_ID" \
  YOUTUBE_OAUTH_CLIENT_SECRET="YOUR_DESKTOP_CLIENT_SECRET" \
  node dist/cli/index.js setup
node dist/cli/index.js login
node dist/cli/index.js status

Windows PowerShell:

$env:YOUTUBE_OAUTH_CLIENT_ID  = "YOUR_DESKTOP_CLIENT_ID"
$env:YOUTUBE_OAUTH_CLIENT_SECRET = "YOUR_DESKTOP_CLIENT_SECRET"
node dist\cli\index.js setup
node dist\cli\index.js login
node dist\cli\index.js status
Remove-Item Env:\YOUTUBE_OAUTH_CLIENT_SECRET

シェルの履歴やプロセステーブルにシークレットを一切残さないようにするには、両方の変数を省略して setup にプロンプトで入力させます。

node dist/cli/index.js setup

ターミナルが対話型の場合、setup は不足している各値をプロンプトで求めます。

login は Google の認証ページを開き、PKCE S256 とランダムな state 値を使用して、127.0.0.1 のランダムなループバックポート経由で戻ります。プロファイルにクライアントシークレットが保存されていない場合は、ブラウザを開く前にすぐに失敗します。

保存された認証情報を取り消して削除するには:

node dist/cli/index.js logout

ステップ 7 — サーバーを起動する

YOUTUBE_API_KEY="your-api-key" node dist/cli/index.js serve

サーバーは stdio 経由で MCP を話すため、通常は手動ではなくクライアントから起動されます。利用可能なコマンドは serve、doctor、status、setup、login、logout です。

ローカルデータの場所

プロファイル、クォータ台帳、ドラフト、操作ジャーナルは 0700 ディレクトリに保存されます。

YOUTUBE_MCP_DATA_DIR で上書きできます。ローカル状態をすべて削除するには、logout を実行してからそのディレクトリを削除してください。キーチェーンエントリは logout によって削除されます。

ローカルビルドにクライアントを接続する

パッケージが公開されるまでは、クライアントにビルド済みの dist/cli/index.js の絶対パスを指定してください。

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default \
  --env YOUTUBE_API_KEY=your-api-key -- \
  node /absolute/path/to/Youtube\ MCP/dist/cli/index.js serve

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default",
        "YOUTUBE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"
YOUTUBE_API_KEY = "your-api-key"

変更をプルした後は npm run build を再実行してください。クライアントはコンパイルされた dist 出力を実行し、src は実行しません。

このローカルサーバーの Google 認証は、独自の setup コマンドと login コマンドによって実行されます。クライアントレベルの MCP ログインコマンドは、後段の Google OAuth フローを置き換えるものではありません。

公開後のクライアント設定

パッケージがリリースされたら、latest ではなくリリース版を固定してください。これにより、MCP クライアントが予期せず動作を変更することがなくなります。

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.4.0", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default"
      }
    }
  }
}

ネイティブ Windows では、"command": "cmd" を使用し、引数の先頭に "/c", "npx" を付けます。

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.4.0 serve

Codex

codex mcp add youtube \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.4.0 serve

同等の Codex 設定:

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.4.0", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"

一度に追加できる量

ツール呼び出しごとのスキーマ上の上限:

したがって、1 回のプレイリスト作成で上限は 50 曲です。準備したドラフトを既存のプレイリストにコミットすることはまだできないため、50 曲を超えるリストは複数のプレイリストに分ける必要があります。

実際には、1 日のクォータの方が厳しい制約です。Google のデフォルトであるプロジェクトあたり 1 日 10,000 ユニットに対して、50 曲の実行 1 回のコストはおおよそ次のとおりです。

つまり、プロジェクト1つにつき1日およそ50曲のプレイリスト1本分です。同じ日に2回目のフル実行を行うとクォータを使い切り、挿入の途中で失敗します。同じリストを2回準備するのは特にコストがかかります。回答が変わらないのに検索が再度課金されるためです。

クォータは米国太平洋時間の午前0時にリセットされます。これはローカル台帳が使用する日付境界です。

クォータの想定

youtube_quota_status はローカルで観測された使用量を報告するものであり、Googleの公式な残高ではありません。一般ユニットと search.list 呼び出しは別々に追跡されます。Googleが検索呼び出しに別のデフォルトの1日あたりの上限を適用しているためです。

[!WARNING] 既知の制限: ローカル台帳は各 search.list を一般ユニット1 + 検索呼び出し1として記録しますが、Googleはこれに100ユニットを課金します。そのため、検索を多く行った後は、general_units は検索1回あたり99ユニット分、実際の消費量を過小報告することになり、報告値がまだ低く見えている間に書き込みがクォータで拒否される可能性があります。この問題が修正されるまで、search_calls の数を重要なシグナルとして扱ってください。プレビューには、コミットの書き込み部分について estimated_commit_units の値が引き続き表示されます。

クォータの値は変更される可能性があります。実装およびリリース作業では、このREADMEの値を恒久的な定数として扱うのではなく、現在の公式コスト表を確認する必要があります。

トラブルシューティング

コミットが status: "partial" を報告し、completed が空で、すべてが pending になっている。 プレイリストは作成されましたが、最初の挿入が拒否されました — 最も多いのは1日あたりのクォータです。何も盲目的に再試行されないため、重複アイテムが書き込まれることはありません。youtube_quota_status を確認し、空のプレイリストを削除し、太平洋時間のリセット後に再実行してください。ドラフトは使い捨てなので、再実行には新しい youtube_prepare_music_playlist が必要です。

login がブラウザを開く前に失敗する。 プロファイルにクライアントシークレットが保存されていません。最初に setup を実行し、意図した YOUTUBE_MCP_PROFILE にいることを確認してください。

認証は成功するが、約1週間後に機能しなくなる。 TestingステータスのままのGoogle OAuthプロジェクトは、7日後に期限切れとなる更新トークンを発行します。同意画面を公開するか、login を再実行してください。

公開読み取りで 403。 YOUTUBE_API_KEY がサーバーの環境にありません。これは永続化されないため、MCPクライアント設定の env ブロックを含め、起動のたびに存在している必要があります。

認証モデル

• 公開読み取りには、プロセス環境に YOUTUBE_API_KEY が必要です。

• アカウント読み取りには、youtube.readonly スコープを持つOAuthが必要です。

• プレイリスト作成には youtube.force-ssl が必要です。Googleがプレイリスト専用スコープを提供していないためです。

• サーバーは、厳格なエンドポイント許可リストによって、その広範なGoogleスコープを相殺しています。呼び出し可能なのはプレイリストおよびプレイリストアイテムの書き込みエンドポイントのみです。

• インストール型アプリケーションは、Authorization Code + PKCE、ランダムな state、およびランダムなポート上の 127.0.0.1 へのループバックリダイレクトを使用します。

• 通常のYouTubeアカウントではサービスアカウントはサポートされていません。

APIキー、OAuthクライアントデータ、アクセストークン、更新トークン、ローカルデータベース、デバッグログ、または .env ファイルをコミットしないでください。

キャプションとアナリティクス

一般的な公開トランスクリプトの取得はv1の対象外です。公式のキャプション取得エンドポイントは権限で制限されておりコストが高いため、非公式のスクレイピングは使用しません。所有者が許可したキャプション管理は、後で検討される可能性があります。

YouTube AnalyticsおよびReporting APIも先延ばしにされています。これらは別のOAuth、データモデル、運用上の動作を必要とするため、最初のプレイリスト中心のサーバーを複雑化させるべきではありません。

開発

実装されたスタックは、TypeScript、Node.js 20.17+、ESM、公式MCP TypeScript SDK、Zod検証、承認されたGoogleエンドポイントへの直接の型付きREST呼び出し、ローカルのクォータ/ドラフト/ジャーナル状態用のSQLite、およびOAuth更新トークン用のOSキーチェーンアダプターです。

現在のチェック:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

実装は PLAN.md のフェーズと受け入れゲートに従う必要があります。エージェント固有の制約と完了の定義は AGENTS.md にあります。Claude Codeは CLAUDE.md から開始する必要があります。

プロジェクトの状況

• 製品およびセキュリティアーキテクチャ

• リポジトリ開発手順

• TypeScriptパッケージのスキャフォールド

• 公開読み取りツール

• OAuthとプロファイル

• 音楽マッチングとプレビュー

• 確認済みの新規プレイリスト作成

• プレビュー済みのプレイリスト更新、並べ替え、削除

• 音楽ドラフトコミットの既存プレイリストターゲット

• クォータ台帳における search.list の一般ユニット会計の修正

• クロスクライアント統合テスト

• 最初のnpmリリース

ライセンス

Apache License 2.0の下でライセンスされています。完全なライセンステキストは LICENSE にあります。

参照

• Model Context Protocol

• YouTube Data API v3

• YouTube Data APIのクォータコスト

• インストール型アプリ向けGoogle OAuth

• Claude MCPドキュメント

• Codex MCPドキュメント