ytmusic-mcp

MCP サーバーであり、ytmusicapi をラップして、Claude（または任意の MCP クライアント）が YouTube Music の検索、プレイリストの管理、リスニング履歴の読み取りを行えるようにします。

ツール

含まれていません（v1）： BPM ベースのレコメンデーション。YouTube Music はテンポデータを公開していないため、これには別のデータソース（例：オーディオ分析 API）が必要になります。これは将来のバージョンでのストレッチゴールであり、今回のビルドには含まれていません。

Related MCP server: mcp-server-youtube

セットアップ

1. 依存関係のインストール

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. 認証

公式の YouTube Music API は存在しないため、ytmusicapi はログイン済みのブラウザセッションのヘッダーを再利用して認証を行います。

1. ログインした状態で Firefox（推奨 – 生ヘッダーのコピーが Chrome よりも信頼性が高い）で music.youtube.com を開きます。

2. DevTools（Cmd+Option+I / F12）→ Network タブ → browse でフィルタリングします。

3. プレイリストをクリックするか、ページをリロードして、browse POST リクエストをトリガーします。

4. そのリクエストをクリック → Headers タブ → Raw headers に切り替え → ブロック全体を選択してコピーします。

5. それをプロジェクトルートに raw_headers.txt という名前の新しいファイルに貼り付けて保存します。

6. 以下を実行します：

   python scripts/setup_auth_from_file.py

   これにより、headers_auth.json が書き込まれ、raw_headers.txt が削除されます。

または、python scripts/setup_auth.py は、ファイルの代わりにインタラクティブなターミナルプロンプトを介して同じことを行います（直接貼り付けたい場合に便利です）。

headers_auth.json はログイン済みセッションと同等です – これをコミットしたり共有したりしないでください。 すでに gitignore されています。

先に進む前に認証が機能することを確認してください：

python scripts/test_search.py

これらのヘッダーは定期的に期限切れ/ローテーションします。認証エラーでツールが失敗し始めた場合は、この手順をやり直してください。

3. Claude Code に追加

claude mcp add ytmusic -s user \
  -e YTMUSIC_AUTH_PATH="$(pwd)/headers_auth.json" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user を指定すると、このディレクトリだけでなく、任意の Claude Code セッションで使用できるようになります。サーバーは任意の作業ディレクトリから起動できるため、python インタプリタ、server.py、YTMUSIC_AUTH_PATH には絶対パスを使用してください。

他の MCP クライアント（Claude Desktop など）の場合は、それぞれの設定形式を使用して、同じコマンドと環境変数を指定します。

エラーハンドリング

ツールコールは、一般的な障害モードを生のトレースバックではなく、明確なメッセージに変換します：

• 認証情報の欠落/期限切れ/不正 → scripts/setup_auth_from_file.py を再実行するように指示します。

• レート制限（HTTP 429） → 待ってから再試行するように指示します。

• ゲート/制限付きコンテンツ → クラッシュする代わりに利用不可として報告します。

• ネットワークエラー → 直接報告します。

ライセンス

MIT – LICENSE を参照してください。