applemusic-mcp

applemusic-mcp

适用于 Apple Music 的 MCP 服务。它让任何 MCP 客户端（Claude、Cursor、Cline、Windsurf）都能控制你的播放列表、资料库、目录、发现、播放和「接下来播放」队列。可在 macOS、Windows 和 Linux 上运行。

你只需要一台 Mac 或 Apple Music 订阅。

"创建一个名为 Road Trip 的播放列表，并加入欢快的 90 年代另类摇滚歌曲。" · "随机播放我的健身播放列表，然后把 Bohemian Rhapsody 加入队列。" · "我最近都在听什么？现在的热门歌曲又有哪些？"

选择它可以访问的内容

你可以在 MCP 客户端的配置中决定此服务可以访问哪些内容。助手无法更改此设置，而且需要超出授权范围的工具根本不会提供给它。

--level	可访问内容	适用场景
music	仅限 Mac 上的 Music 应用。无网络访问，也不使用浏览器。	你的资料库、播放列表、播放、评分、AirPlay
api	+ Apple 的音乐服务（通过互联网）	从完整目录搜索并添加内容、获取推荐、在 Windows 和 Linux 上使用
web	+ Safari 或 Chrome 网页播放器	「接下来播放」队列，以及在 Mac 以外的设备上播放
full	所有内容，包括在 Music 应用中点击操作	使用所有功能，无需选择
--allow-ui（适用于任意级别）	+ 在 Music 应用中点击操作（macOS 辅助功能）	无需登录即可播放目录中的歌曲

从 music 开始；需要更多功能时再提高级别。目前，如果省略 --level，效果与 full 相同，和 0.21 之前一样。

如果你想要一款提供引导式设置而非终端命令的 Mac 应用，可以考虑社区分支 secure-applemusic-mcp-for-osx。

功能

各引擎支持的功能，以及启用这些功能所需的级别。✓ 表示支持，✗ 表示不支持，— 表示不适用。

能力	Music.app（macOS）· music	Apple Music API（任意操作系统）· api	网页播放器（Safari / Chrome）· web
目录搜索 / 浏览	✓	✓（+ 无令牌解析）	—
推荐 / 榜单 / 建议	✗	✓	—
资料库搜索 / 浏览	✓	✓	—
流派搜索	✓	✗	—
最近播放 / 添加的内容	✓	✓	—
添加目录内容 → 资料库	✓	✓	✓（页面内 POST）
从资料库移除	✓	✓	—
喜爱 / 不喜欢	✓	✓	—
1–5 星评分	✓	✗	✗
收藏列表	✓	✗	✗
播放列表 创建 / 添加 / 移除 / 重命名	✓	✓	—
复制播放列表	✓	✗	—
删除播放列表	✓	✓（网页令牌）	—
文件夹：单层 + 移入 / 移出	✓	✓	—
文件夹：嵌套路径 / 树 / path	✓	✗	✗
播放：播放歌曲 / 专辑 / 播放列表 / URL	✓	—	✓
控制：暂停 / 停止 / 下一首 / 上一首 / 快进或快退	✓	—	✓
设置：音量 / 随机播放 / 重复播放	✓	—	✓
now_playing	✓	—	✓
「接下来播放」队列：查看 / 下一首 / 最后一首 / 移除 / 跳转 / 清空 / 自动播放	✗	—	✓
在应用中显示	✓	—	✓（跳转至页面）
选择 AirPlay 设备	✓	✗	✗
资料库快照 / 完整性	✓	✗	✗
无需 Apple 账户即可使用	✓	✗	✗
跨平台（Win/Linux）	✗	✓	✓

Music.app 的目录搜索和目录播放会在应用中执行点击操作，因此即使设置了级别，也需要 --allow-ui。网页播放器中的播放和队列需要桌面会话：Mac 上的 Safari（无需安装任何内容），或其他设备上的 Google Chrome。如何选择和覆盖引擎：配置。

设置

**要求：**Python 3.10+，以及一台 Mac 或 Apple Music 订阅。在 Mac 上无需其他条件。Chrome 网页播放器（Windows、Linux，或选择在 Mac 上使用）需要Google Chrome。

Claude Code，一行命令：

claude mcp add "Apple Music" -- uvx applemusic-mcp serve --level music

Claude Desktop / Cursor / Cline / Windsurf，安装一次，然后添加配置块：

pipx install applemusic-mcp        # or: pip install applemusic-mcp
playwright install chromium        # the Chrome web player: Windows/Linux, or a Mac with the [browser] extra

{
  "mcpServers": {
    "Apple Music": {
      "command": "applemusic-mcp",
      "args": ["serve", "--level", "music"]
    }
  }
}

将 music 改为 api 或 web，以解锁更多功能；在 Windows 或 Linux 上，请从 api 开始，因为 music 需要 Mac。配置文件位置、Mac 上的 Chrome 网页播放器以及源码安装：配置。

重启客户端，然后尝试 "列出我的 Apple Music 播放列表" 或 "播放我的最爱"。在 macOS 上，本地资料库和播放功能可立即使用。要添加目录音乐或在任何操作系统上运行，请登录。

登录

api 和 web 模式需要登录。此工具不会接触你的密码，登录状态会持续保留。

applemusic-mcp login            # Mac: reads your signed-in Safari. Windows/Linux: opens Chrome
applemusic-mcp status           # verify

在 Mac 上，请先在 Safari 中登录 music.apple.com，并仅需开启一次 Safari 的 Develop → Allow JavaScript from Apple Events；login 会准确提示缺少哪些设置。对于批量操作（导入播放列表、迁移资料库），请使用自己的 Apple 开发者令牌，以避开共享速率限制。详情、Chrome 和开发者令牌的使用方式，以及各项写入操作使用的 API：登录说明。

工具

七种基于操作的工具可保持 MCP 上下文精简。每种工具都接受一个 action，并路由至合适的引擎。

工具	操作
playlist	list、folders、tracks、search、create、add、copy、move、remove、delete、rename、path（播放列表和文件夹）
library	search、add、browse、favorites、recently_played、recently_added、rate、remove、snapshot
catalog	search、resolve、album_tracks、album_details、song_details、artist_details、genres、suggestions
discover	recommendations、heavy_rotation、charts、top_songs、similar_artists、personal_station、song_station
playback	play（曲目 / 专辑 / 播放列表 / URL）、control、now_playing、settings、reveal、airplay
queue	list、set、play_next、play_last、remove、jump、clear、autoplay（即将播放 — macOS 上使用 Safari，其他系统使用 Chrome；用 engine= 选择）
config	status、signin、logout、reset、set-pref、audit-log、clear-audit-log、list-storefronts

批量操作、导入播放列表、试运行、导出格式和 storefront：使用模式。

CLI

applemusic-mcp serve --level music   # run the MCP server (your client calls this)
applemusic-mcp login                 # web sign-in (macOS: Safari; Windows/Linux: Chrome)
applemusic-mcp login --chrome        # use the Chrome web player on a Mac
applemusic-mcp login --dev           # your own Apple developer token (.p8)
applemusic-mcp logout                # sign out (switch accounts)
applemusic-mcp status                # auth status and permission level
applemusic-mcp reset --force         # wipe credentials (keeps your .p8 key file)
applemusic-mcp reset --all --force   # full uninstall: also removes the .p8, profile, and cache

注意事项

• **在 Music.app 中播放目录歌曲需要 --allow-ui、已解锁的屏幕和辅助功能权限。**它会在应用中点击“播放”。资料库中已有的歌曲不需要这些条件。或者，在 --level web 模式下，设置 mode="safari"，改为在 Safari 中播放。
• **Safari 播放需要先进行一次真实点击。**首次在刚打开或重新加载的 Safari 标签页中播放时，浏览器要求先进行真实点击才会开始播放音频（这是标准的自动播放规则——我们不会伪造点击）。在 Apple Music 标签页中点击一次 ▶，之后即可免手动操作地播放、暂停和切换下一首。如果播放命令提示队列已就绪，但曲目时间仍停在 0:00，就是这个原因——点击一下该标签页即可。
• 全新创建的播放列表需要稍等片刻才能通过 API 添加曲目（云端同步需要时间）。已有播放列表则可立即使用。
• 如果目录操作开始失败，请重新运行 applemusic-mcp login。少数用户播放列表会悄无声息地撤销 AppleScript 编辑（Music.app 已知问题）；服务会检测并报告回滚。

Star History

---

许可证

MIT · 非官方社区项目——与 Apple 无关，也未获 Apple 认可。个人使用时使用你自己的 Apple Music 账户；请遵守 Apple 的条款。

mcp-name: io.github.epheterson/applemusic-mcp

致谢

FastMCP · Apple MusicKit · Model Context Protocol

---

由 @epheterson 和 Claude Code 在加利福尼亚倾情打造 ❤️。