Apple Music Playlist Curator

Apple Music MCP キュレーター

网易云（NCM）の公開プレビュー：簡体字中国語の使用方法。

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Português do Brasil | Deutsch | Français

Apple Music向けの綿密なプレイリストキュレーション：気分、情景、時代、聴く目的、またはサウンドを伝えると、エージェントが選曲の根拠を示し、流れを整えて、満足感のあるリスニング体験を作り上げます。物語の展開は自由に指定できます。指定がない場合、ストーリー展開は設定されません。

12曲のキュレーションデモを見る：根拠に基づいて選ばれた22曲の候補が、意図的に指定された三幕構成の物語へとまとまります。また、オプティマイザーのコストが低くても、プレイリストの質が下がることがある理由も示します。これは一つの構成例であり、既定のテンプレートではありません。

Python標準ライブラリのみを使用するため、実行にpip installは不要で、Apple Developer Programへの加入も必要ありません。Python 3.10+が必要で、Windows／macOS／Linuxで動作します。

主なインターフェースは、ローカルのam-mcp stdioサーバーです。MCPクライアント上ですでに動作している言語モデルが依頼内容を解釈し、候補を選びます。このプロジェクトはApple Musicカタログを検索し、正確なトラックを特定して、アカウント操作を実行します。モデル、LLM APIキー、アーティストリスト、固定テーマは同梱されていません。CLIも、ログイン、診断、スクリプト実行、監査、高度な曲順の設定に引き続き使用できます。

  understand  →  curate  →  ground  →  sequence with intent  →  dry-run  →  create

このプロジェクトについて

• 概要は意味に基づいています。 ホスト LLM は、イメージ、ムード、歌詞の切り口、時代、文化的背景、対比、各曲の役割を直接推論します。ユーザーが指定したわずかなスライダーや、不透明なテーマ適合度の数値に還元されることはありません。
• 選曲と曲順の決定は分けて行います。 何を含めるかはモデルが判断します。測定された BPM、キー、エネルギー、感情価、ラウドネスは、トランジションの診断や、指定したビート内での流れの調整に利用できます。指定がなければ、全体の展開は強制されません。
• すべての候補に根拠があります。 カタログ照合では、ドライランと最終作成の前に、トラックの欠落、重複、アーティストの誤り、ライブ版やリマスター版の疑いがあるものを検出します。
• 再生履歴はあくまで判断材料です。 再生履歴、最近の再生、日付、再生回数を選曲の参考にできますが、ユーザーの好みを定義するアルゴリズムに暗黙のうちに組み込まれることはありません。
• ローカルでプライベートに使えるよう設計されています。 サーバーはお使いのマシンで動作します。認証情報はローカルのアプリ設定に保存され、同梱モデル、テレメトリサービス、追加の LLM API キーはありません。
• 移植可能な MCP stdio。 Codex、Claude、Cursor、VS Code/Copilot、Gemini CLI、Windsurf、Cordis/DSH、Harness、およびローカルの stdio サーバーを起動できるその他のクライアントで動作します。

クイックスタート

おすすめ — MCP stdio サービスをインストールします：

pip install apple-music-playlists
am-playlist status
am-playlist login       # one-time Apple ID sign-in

すでに uv をお使いですか？ 永続的にインストールせずに、公開済みパッケージを実行できます：

uvx --from apple-music-playlists am-playlist status
uvx --from apple-music-playlists am-playlist login
uvx --from apple-music-playlists am-mcp

MCP クライアントでは、Registry に準拠した同等の設定を使用できます：

{ "mcpServers": { "applemusic": { "command": "uvx",
    "args": ["--from", "apple-music-playlists", "am-mcp"],
    "env": { "PYTHONIOENCODING": "utf-8" } } } }

クライアントに am-mcp を登録します。一般的な設定形式は次のとおりです：

{ "mcpServers": { "applemusic": { "command": "am-mcp",
    "env": { "PYTHONIOENCODING": "utf-8" } } } }

実装方法ではなく、作成したい結果を説明してください：

深夜のドライブに合う、25 曲のプレイリストを作成してください。雰囲気のあるオルタナティブ R&B とエレクトロニックを中心に、ほとんどを過去 10 年間の曲にし、ライブ版は含めず、穏やかな締めくくりにしてください。

MCP プロンプトに対応したクライアントでは、create_playlist_from_description を選択できます。それ以外のすべてのクライアントでは、チャットで同じリクエストを送信してください。サーバーの指示と型付きツールにより、同じステータス → 候補プール → カタログ照合 → 直接比較 → ドライラン → 作成のワークフローを利用できます。

クローンから実行する場合（インストール不要）：

git clone https://github.com/Z-Han-Z/apple-music-playlists.git
cd apple-music-playlists

python am_playlist.py status     # auto-fetches the developer token
python am_playlist.py login      # one-time Apple ID sign-in (~6 months validity)

python am_mcp_server.py             # register this absolute script path in the MCP client

インストールすると、CLI コマンドと MCP コマンドも PATH に追加されます：

am-playlist status      # the CLI
am-playlist login       # one-time Apple ID sign-in
am-mcp                  # the MCP stdio server

開発時は、クローンから pip install -e . を実行すると、再インストールせずに編集内容が反映されます。

認証情報の設定手順（ユーザートークンを取得する 3 つの方法。依存関係ゼロの方法を含みます）については、SETUP.en.md をご覧ください。

実際のキュレーションのデモ：A Machine Dreams It Is Human

これは「ワークアウト用のプレイリストを作って」よりも、意図的に難しい依頼です。この依頼では、音楽で物語を紡ぐことが求められています。また、その制約の中には、テンポやムードのスライダーでは表現できないものもあります。

機械が都市で目覚め、注目を親密さと取り違え、触れてほしいと求め、心を開いて、夜明けを見る、全12曲・三幕構成の物語を作ってください。1970年代後半から現在までのエレクトロニックミュージックとアートポップを組み合わせ、アーティストごとに1曲とし、スタジオ録音のみを使ってください。また、歌声が徐々に人間らしくなるようにしてください。結末は、単にエネルギーが低いのではなく、静かで、積み重ねの感じられるものにしてください。

以下の実行では、2026-09-23 時点の公開されている米国の Apple Music カタログを使用しました。非公開のライブラリは読み取りも書き込みもしていません。

22 LLM-proposed candidates
└─ 22 catalog matches returned exact title, artist, album, date, ISRC, and version metadata
   ├─ rejected: “Open Eye Signal (Mixed)” — resolved to a 2025 DJ Mix, not the studio cut
   ├─ rejected: “Deeper Understanding (2018 Remaster)” — not the requested original recording
   └─ 12 final selections

Final create dry-run:       12/12 matched; no write performed
Audio-feature coverage:     12/12 usable (100%)
Flow cost, narrative locks: 44.14 → 41.14

以下の各タイトルを開くと、リゾルバーが返した米国カタログ上の該当録音を直接確認できるため、順序をそのまま信頼するのではなく、実際に試聴できます。

興味深い失敗は、曲順の最適化中に起きました。三幕だけを固定した場合、数値最適化器は測定コストを 48.28 から 14.88 に下げましたが、Retrogradeを夜明けの後に配置し、まだ起きていない要求への返答としてAll Is Full of Loveを置いてしまいました。コストは下がっても、結果は悪くなっています。そこでホストモデルが意味上のビートの境界（request → answer、return → dawn）を追加し、am_optimize_orderにはその境界の内側でのみ局所的な変更を許可しました。選曲と物語の構成は言語的な判断に委ね、BPM、キー、エネルギー、バレンスは補助的な根拠として扱いました。

[
  "The Robots - Kraftwerk",
  "Technopolis - Yellow Magic Orchestra",
  "Kid A - Radiohead",
  "Oblivion - Grimes",
  "Digital Witness - St. Vincent",
  "Is It Cold In The Water? - SOPHIE",
  "Touch - Daft Punk",
  "All Is Full of Love - Björk",
  "Cellophane - FKA twigs",
  "Retrograde - James Blake",
  "Long Road Home - Oneohtrix Point Never",
  "An Ending (Ascent) - Brian Eno"
]

これは一般的な MCP ワークフローです。ホストモデルが依頼を解釈し、必要数より多くの候補を提案します。am_resolve_candidatesで候補を確定し、依頼で求められた場合にのみ、モデルが曲を選んで物語上の役割を解釈します。am_optimize_orderでは意味上の境界を越えずに局所的な流れを任意で確認し、最後にam_create_playlist(dry_run=true)で書き込み前に最終的な録音を正確に検証します。

このワークフローを一発生成のベースラインと比較するには、**examples/**にある、難易度の高い6つの多言語の依頼とブラインド試聴のプロトコルを使用してください。このテストスイートが示すのは監査可能な制約であり、あらかじめ決められた「正解」の曲ではありません。

内容物

補助モジュール：

3 つの分析モジュールはすべて、ライブラリとしてインポートできます。

import playlist_flow, playlist_audit, playlist_optimize

print(playlist_flow.flow_report("My Playlist"))          # -> str
print(playlist_audit.audit_report("My Playlist"))        # -> str
ids, report = playlist_optimize.optimize("stack.json")   # -> (list[str], str)

MCP ツール

標準プロンプト create_playlist_from_description では、自然言語による概要と、任意の名前、トラック数、応答言語を指定します。選曲はホストモデルが行い、ツールは Apple Music を操作するための根拠に基づいた実行レイヤーです。

am_status · am_search_songs · am_resolve_candidates · am_list_playlists · am_show_playlist · am_create_playlist · am_add_tracks · am_delete_playlist · am_audit_playlist · am_analyze_flow · am_optimize_order · am_recently_played · am_top_played

am_resolve_candidates は、LLM が提案した候補プールを実際のカタログメタデータに照らして確認し、重複や不審なバージョンにフラグを立てます。また、テーマへの適合度は意図的に評価しません。ホストモデルは候補をユーザーの言葉と直接照らし合わせ、それぞれのプレイリスト内での役割を説明します。 am_analyze_flow はトランジションを診断します。am_optimize_order は、すでに選ばれたナラティブブロック内の並び順を任意で調整できます。プレイリストに入れる曲を決めることはありません。

preset/ のテンプレートを使って Cordis エージェントプリセットに組み込むか、次のように任意の MCP クライアントに接続します。

{ "mcpServers": { "applemusic": {
    "command": "python", "args": ["/abs/path/am_mcp_server.py"] } } }

Codex、Claude、Cursor、VS Code/Copilot、Gemini CLI、Windsurf、Docker、Cordis/DSH、Harness 向けの、テスト済みの完全な例は docs/client-setup.md にあります。

非 root のローカルコンテナをビルドするには、次を実行します。

docker build -t apple-music-playlists:1.5.0 .

クライアントからは、docker run --rm -i を使ってアタッチした状態で実行してください。クライアントガイドに示すとおり、マウントするのはアプリ設定ディレクトリと書き込み可能なキャッシュのみです。トークンの更新を保存できるよう、設定は書き込み可能な状態にしておきます。 Apple の認証情報をイメージに埋め込まないでください。

テスト

python -m unittest discover -s tests -v

テストスイートは完全にオフラインで実行でき、ネットワークも認証情報も不要です。テストは次の2種類です。

• 動作テスト：「心地よく聴こえる」かどうかを決める純粋な数学的処理を検証します。Camelot マッピング、BPM の折り返し、アークの分類、各隣接ペナルティの個別検証、アニーリングの決定性、ブロック順序の制約が対象です。6つすべてのナラティブアーキタイプが、それぞれ自身として分類される必要があります。
• 構造的なリグレッションテスト：実際にリリースされたバグを1つずつ防ぎます。カタログの地域がハードコードされていないこと、catalog_meta がちょうど1つだけであること、--storefront のデフォルト値が None 以外に設定されていないこと、キャッシュがリポジトリの外にあること、すべての MCP ツールがハンドラーに接続されていること、オプティマイザーにプラットフォームのインポートがないことを検証します。

このテストスイートはすぐに役立ちます。数分前に書かれたファイルの構文エラーを、実行する前に検出しました。

興味深い部分：オーディオ特徴

Apple のカタログ API では、テンポ、キー、ラウドネス、エネルギー、バレンスなどのオーディオ特徴は一切公開されていません。Spotify の audio-features エンドポイントは2024-11-27に新しいアプリ向けの提供を終了し、AcousticBrainz は2022年にサービスを終了しました。

playlist_flow.py は、Apple が返す ISRC を使い、無料でキー不要の連携を通じてこのギャップを埋めます。

Apple Music track  ──►  ISRC
                          │
                          ├─► api.reccobeats.com/v1/track?ids=<ISRC>   → track UUID
                          │        └─► /v1/audio-features?ids=<UUID>
                          │                 → tempo, key, mode, loudness, energy, valence,
                          │                   danceability, acousticness, instrumentalness,
                          │                   liveness, speechiness
                          └─ (fallback) musicbrainz.org ISRC lookup

結果はローカルにキャッシュされるため、ネットワークコストがかかるのはプレイリストごとに一度だけです。

カバレッジは報告し、黙って除外することはありません。 各コンシューマーは、各トラックを測定できなかった理由を示すファネルを出力します。

Audio-feature coverage: 1,395/1,581 usable (88%)
  ·  80 tracks have no ISRC — the feature chain cannot start, so changing sources will not help
  · 106 tracks are not in the current source — switch sources or analyse the audio locally

この違いが重要です。ISRC がない場合、連携をそもそも開始できません。別の特徴ソースに切り替えても解決しません。ソースに存在しない場合は、ISRC に問題はなく、ソースの切り替え（または音声のローカル分析）で解決できます。どちらも「特徴が欠けている」とまとめてしまうと、次に何をすべきかを判断するための唯一の情報が失われます。

これは見た目以上に重要です。tempo／key／energy／valence は、隣接ルールとアークが処理できる唯一の要素です。そのため、カバレッジが並べ替えの品質の上限を決めます。カバレッジが60%なら、10個のうち4つの位置は評価されていないのに、コストの数値は依然として優秀に見えてしまいます。そこでオプティマイザーはコストの行より先にカバレッジを出力し、90%を下回ると警告します。

オプティマイザーが適用するシーケンス規則

docs/ にまとめられた研究に基づいています。これには、130 人の音楽専門家がアルバムの曲順を決めた PLOS ONE の研究と、気分に応じて曲順を変える音楽のランダム化試験が含まれます。

隣接に関する必須ルール

• 遅い曲を 2 曲連続させない
• 「わずかに遅くなる」遷移を避ける（速度が 0～12％低下すると、遅い曲がもたついて感じられます）
• 隣り合う曲は、テンポとキーの両方が似ていてはいけません
• 正当化できない大幅な BPM の変化（40％超）を避けること。相性の悪いキーのもとで、唐突にエネルギーが変化することも避けます

この 4 つのルールの定義は playlist_core.check_pair() に一元化されており、監査とオプティマイザーの両方がこれを呼び出します。以前は 2 か所に実装されていて、定義に食い違いがありました。監査ではテンポの 25 パーセンタイル未満の曲を「遅い」とみなしていましたが、オプティマイザーでは固定値の 100 BPM を使っており、監査は BPM の変化に関するルールをまったく確認していませんでした。つまり、ツールがある基準で診断し、別の基準で修正していたため、報告された件数は信頼できませんでした。

「遅い」曲のしきい値に関する注記。 このしきい値はデータに基づくものではなく、意図的に絶対値（100 BPM）にしています。オプティマイザーはアニーリング中に同じシーケンスを何千回も評価しますが、パーセンタイルのしきい値は順列の変化に応じて変動するため、コストが収束しなくなるからです。その代償として、全体的に遅いプレイリストではすべての隣接ペアにフラグが付きます。これはシーケンスの失敗ではなく、実際の状態であり、レポートにもその旨が記載されます。

全体的な物語の流れは任意です。 --arc を指定しない場合、オプティマイザーは局所的な曲の隣接関係のみを考慮し、感情やテンポの推移は課しません。ホストの LLM が概要から自由形式のストーリーを解釈し、その順序をブロックごとに保つ必要があります。名前付きプリセットを使うのは、ユーザーがそのような曲線を明示的に求めた場合に限ります。

python playlist_optimize.py stack.json --arc cinderella
python playlist_optimize.py --list-shapes

任意で選べる形状は 6 種類です：rags-to-riches、tragedy、man-in-a-hole、icarus、cinderella、oedipus。目標曲線と監査で分類される形状は、同じ playlist_core.ARCHETYPES テーブルに基づきます。監査では、プレイリストがどのプリセットに似ているかを報告することがあります。ただし、その診断によってプリセットが推奨されたり、曲順の目標になったりするわけではありません。

プリセットを明示的に指定した場合、valence／energy／loudness はその感情的な推移に沿い、テンポには独立した逆 U 字型の目標が適用されます。--arc を指定しない場合、どちらの全体目標も適用されません。

アークのコストは、明示的に指定された特徴量の曲線との距離であり、プレイリストの良し悪しを測るものではありません。カバレッジによって説明できる範囲は限られます。また、コストが低くても、概要を覆したり、ある曲順のほうが聴いて心地よいと証明したりすることはできません。

オプティマイザーはグループ分け（組曲／時代／ムード）を保ち、グループ内でのみ曲順を変更するため、ラウドネスの調整後もテーマの構成が維持されます。グループ分けを解除すると自由に並べ替えます。測定可能な意味で「より滑らか」になりますが、物語性は損なわれます。

実際の実行例：グループ分けを維持した場合、コストは 104.46 → 19.41。グループ分けを解除した場合は → 1.28。

デバッグ前に知っておきたい注意点

• Accept-Encodingを送信していなくても、レスポンスがgzip圧縮されている場合があります。 生のバイト列をUTF-8としてデコードすると、中身が空のように見える文字化けが発生します。（これはam_playlist.pyで修正済みです。）
• DELETEが機能するのはamp-api.music.apple.comのみです。 ドキュメントに記載されているホストapi.music.apple.comでは、プレイリストとライブラリ内の曲の削除時に401が返されます。
• amp-apiにはx-apple-client-versionを送信しないでください。 送信すると500エラーになります。
• プレイリストを作成すると、収録曲もライブラリに追加されます。 プレイリストを削除しても、曲は削除されません。
• BPMの推定値にはオクターブの曖昧さがあります（同じ曲でも90と180になる場合があります）。比較前に[70,160)の範囲に収めてください。そうしないと、「テンポの遅い曲が2曲続く」という判定が約4倍過剰になります。
• 「曲名 - アーティスト名」をそのままカタログ検索に渡さないでください。 ライブ版やリマスター版が見つかります。スペース区切りの形式で検索し、その後にバージョンをスコアリングしてください。
• あるストアフロントの検索でアーティストが見つからないことは、そのストアフロントで曲を利用できないことを意味するわけではありません。 ISRCで検索してください。
• プレイリストを変更できるのは、作成したクライアントのみです（Apple側の制限です）。

詳細はdocs/apple-music-api-notes.mdおよび skill/reference.mdをご覧ください。

ドキュメント

簡体字中国語版の完全なガイドについては、**README_ZH_CN.md**をご覧ください。

コミュニティ

• コントリビューション — 開発ワークフロー、アーキテクチャ上の境界、およびレビューへの期待事項
• サポート — 質問、バグ報告、機能提案を行う場所
• 行動規範 — 参加基準と非公開の報告窓口
• セキュリティポリシー — サポート対象バージョンと機密性の高い脆弱性報告

ライセンス

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

非公式のコミュニティツールです。Apple との提携や、Apple による推奨を受けていません。 個人利用にはご自身の Apple Music アカウントを使用してください。Apple の利用規約に従ってください。