YouTube MCP サーバー

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 サポート。

Related MCP server: youtube-music-mcp

計画中の v1 スコープ

読み取りツール

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

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

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

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

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

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

• 可能性の高い YouTube ミュージックビデオの一致候補を検索してランク付け。

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

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

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

コメント管理

• 動画にトップレベルコメントを投稿、または既存のコメントに返信。

• プレビューとワンタイムハンドルを経て、コメントを削除、またはモデレーションステータスを設定。

• プレイリスト書き込みで既に要求されている youtube.force-ssl スコープを使用するため、追加の同意は不要。

プレイリスト管理

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

• プレイリストのメタデータまたはプライバシーを更新。

• プレイリスト項目を並べ替えまたは削除。

• 短命のワンタイム確認ハンドルが発行された後にプレイリストを削除。

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

動画のアップロードとライフサイクル

• 再開可能なアップロードでローカル動画ファイルをアップロード。デフォルトは private。

• 所有する動画のタイトル、説明、タグ、またはプライバシーを更新。未指定のフィールドはクリアされずに引き継がれます。

• ローカルの JPEG または PNG からカスタムサムネイルを設定。

• 所有する動画をプレビューしてから完全に削除。

動画の書き込みには追加の youtube.upload スコープが必要で、そのスコープなしで認可されたプロファイルでは完全に拒否されます。youtube_plan_video_upload はファイルを検証し、YouTube に問い合わせずにコストを報告します。videos.insert は 1600 ユニット、つまりアップロード 1 回あたりデフォルトの 1 日予算の約 16% を消費するためです。アップロードは決して再試行されません。結果が不明な場合はその旨が報告され、重複を公開する代わりに部分的なアップロードがないか確認できます。

プレイリスト、コメント、動画の管理が実装済みの書き込み面です。アナリティクスレポート (0.8) はロードマップ上にあり、まだ呼び出し可能ではありません。評価、登録、チャンネル設定の書き込みは、恒久的にスコープ外のままです。

セットアップ

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 つ選び、ステップ 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.7.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.7.0 serve

Codex

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

同等の Codex 設定：

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

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

一度に追加できる量

ツール呼び出しごとのハードなスキーマ制限：

つまり、1回のコミットで上限となるのは50曲です。より長いリストは50曲単位のバッチでコミットして処理します。最初のバッチでプレイリストを作成し、以降の各コミットでその target_playlist_id を渡して追加します。すでに存在する重複はスキップされ、2回挿入されるのではなく報告されます。

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

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

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

クォータの期待値

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

search.list は公開されている100ユニットで課金されるため、general_units は実際の消費量を反映します。0.5.0より前のリリースではこれを1ユニットとして記録していたため、検索1回につき99ユニット分の使用量を過小報告していました。報告された数値がまだ低く見えている間に、書き込みがクォータで拒否される可能性がありました。以前のビルドを使用している場合はアップグレードしてください。

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

トラブルシューティング

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

• 動画アップロードとライフサイクルには youtube.upload が必要です。これは別途要求され、このスコープなしで認証されたプロファイルでは動画ツールが拒否されます。同意画面に追加し、アップロード前に login を再実行してください。

• サーバーは、その広範な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とプロファイル

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

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

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

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

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

• コメント挿入、返信、削除、およびモデレーション（0.6）

• 動画アップロード、メタデータ更新、削除、およびサムネイル（0.7）

• YouTube Analyticsレポート（0.8）

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

• 最初のnpmリリース

ライセンス

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

参考

• Model Context Protocol

• YouTube Data API v3

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

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

• Claude MCPドキュメント

• Codex MCPドキュメント