Apple Music Mcp

mcp-apple-music 🎵

mcp-name: io.github.Cifero74/mcp-apple-music

一个 MCP（Model Context Protocol）服务，让 Claude 能够全面访问你的 Apple Music 账户——搜索曲库、浏览个人音乐库、管理播放列表，以及探索听歌历史和推荐内容。

可以向 Claude 提出以下问题：

• “根据我最近听的歌曲，推荐 15 首我还没有的歌曲，并将它们添加到新播放列表中。”
• “显示我的所有播放列表，并告诉我出现频率最高的艺人。”
• “搜索 Nick Cave 的专辑，并将我最喜欢的三张专辑添加到名为 Dark Picks 的播放列表中。”

---

功能

工具	描述
search_catalog	搜索 Apple Music 曲库（歌曲、专辑、艺人、播放列表）
search_library	在个人音乐库中搜索
get_library_songs	列出音乐库中保存的歌曲（分页）
get_library_albums	列出音乐库中的专辑（分页）
get_library_artists	列出音乐库中的艺人
get_library_playlists	列出所有播放列表及其 ID
get_playlist_tracks	获取播放列表或 Apple Music 曲库播放列表（pl. ID）中的曲目
create_playlist	创建新播放列表
add_tracks_to_playlist	将歌曲添加到播放列表（音乐库或曲库中的曲目）
add_to_library	将曲库中的歌曲、专辑或播放列表保存到音乐库
get_recently_played	查看最近播放的专辑、播放列表和电台
get_recommendations	获取 Apple Music 个性化推荐
favorite_song	将曲库歌曲标记为喜爱（加星标）
unfavorite_song	取消喜爱曲库歌曲
get_song_favorite_status	检查哪些曲库歌曲已标记为喜爱

---

要求

• Python 3.10+
• uv（推荐）或 pip
• 付费的 Apple Developer Program 会员资格（每年 99 USD），用于创建 MusicKit 密钥。免费的 Apple Developer 账户无法创建 MusicKit 密钥。
• 有效的 Apple Music 订阅

---

设置

1. 创建 MusicKit 密钥

1. 前往 developer.apple.com → Certificates, Identifiers & Profiles
2. 在 Keys 下，点击 + 创建新密钥
3. 为密钥任意命名，启用 MusicKit，然后点击 Continue → Register
4. 下载 .p8 文件——只能下载一次，请妥善保管！
5. 记下你的 Key ID（例如 ABC123DEF4）和 Team ID（可在 Membership Details 下找到）

⚠️ Key ID 是显示在密钥名称旁的字母数字代码——不是 .p8 文件的文件名。

2. 克隆并安装

git clone https://github.com/Cifero74/mcp-apple-music
cd mcp-apple-music

# with uv (recommended)
uv sync

# or with pip
pip install -e .

3. 运行一次性设置向导

# with uv
uv run mcp-apple-music-setup

# or directly
python -m mcp_apple_music.setup

向导会要求你提供 Team ID、Key ID 和 .p8 文件的路径。随后，它会打开一个浏览器页面，你可以在其中点击 “Authorise Apple Music”——此操作会使用 Apple 官方的 MusicKit JS 获取你的 Music User Token，并将其安全地存储在 ~/.config/mcp-apple-music/config.json 中（文件权限：600）。

4. 添加到 Claude Desktop

打开 Claude Desktop 配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apple-music": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-apple-music",
        "mcp-apple-music"
      ]
    }
  }
}

重启 Claude Desktop——你应该会在工具栏中看到可用的 apple-music 工具。

---

工作原理

Apple Music 需要两个独立的令牌：

• 开发者令牌 — 使用 .p8 私钥在本地签名的 JWT。最长有效期为 6 个月；服务会在令牌过期前自动重新生成。你的密钥不会离开你的设备。
• 音乐用户令牌 — 通过浏览器中的 MusicKit JS OAuth 获取一次（由设置向导处理）。存储在本地的 ~/.config/mcp-apple-music/config.json 中。

Your .p8 key  ──►  Developer Token (JWT, auto-renewed)  ─┐
                                                           ├──► Apple Music API
Browser OAuth ──►  Music User Token (stored locally)    ─┘

⚠️ 播放控制（播放／暂停／跳过）无法通过 Apple 的 REST API 实现。它需要原生 MusicKit 框架（iOS/macOS 应用）或在浏览器环境中运行的 MusicKit JS。

如需播放控制，请试试 chrome-relay——一个配套的命令行工具，可让 MCP 服务控制 Chrome 中已打开的 music.apple.com 标签页，从而实现播放／暂停／跳过，无需随软件附带 MusicKit JS 适配层。

---

项目结构

mcp-apple-music/
├── src/
│   └── mcp_apple_music/
│       ├── __init__.py
│       ├── auth.py      — Developer Token generation + User Token management
│       ├── client.py    — Async HTTP client for api.music.apple.com
│       ├── server.py    — FastMCP server with all 14 tools
│       └── setup.py     — One-time setup wizard (browser-based OAuth)
├── config.example.json  — Example config structure (no secrets)
├── pyproject.toml
└── README.md

---

示例提示词

连接后，你可以向 Claude 提问：

"What have I been listening to this week? Based on that, find 10 songs
 I don't own yet that I'd probably enjoy and create a playlist with them."

"Search for all albums by Joni Mitchell and tell me which ones
 I already have in my library."

"List my playlists, pick the one that looks most like a workout mix,
 and add 5 high-energy songs from the catalog to it."

"Create a playlist called 'Rainy Sunday' with the 10 most mellow tracks
 you can find from my library."

---

作者

由 Cifero74 和 Claude（Anthropic）构建，是 Claude Desktop 个人 MCP 生态系统的一部分。

本项目完全通过 Mario 与 Claude 的协作对话构思、设计、调试并发布——从 API 调研和身份验证流程设计，到设置向导，再到使用真实 Apple Music 音乐库进行现场测试。

欢迎贡献、反馈问题和提交 PR！

---

许可证

MIT — 随意使用、分叉并在此基础上构建。