Apple Music MCP 服务器

苹果音乐MCP服务器

与Apple Music集成的MCP（模型上下文协议）服务器，允许Claude和其他MCP客户端搜索目录、管理播放列表和访问您的库。

特性

• 搜索 Apple Music目录（歌曲、专辑、艺术家、播放列表）
• 列表 您的播放列表并浏览其曲目
• 创建 带有可选初始曲目的新播放列表
• 添加曲目 到现有播放列表
• 浏览 您的库歌曲
• 视图 最近播放的曲目
• 获取 个性化推荐

先决条件

• Node.js 18+
• 一 Apple 开发者计划 会员资格
• MusicKit标识符和私钥

苹果开发者设置

1.创建MusicKit标识符

1. 首选 Apple开发者>证书、标识符和配置文件
2. 点击 + 注册新的标识符
3. 选择 音乐套件ID （或 媒体ID)
4. 输入描述（例如“MCP服务器”）和标识符（例如。， com.yourname.musicmcp)
5. 点击 继续 和 注册

2.创建MusicKit私钥

1. 首选 苹果开发者>密钥
2. 点击 + 创建新密钥
3. 命名它（例如，“MusicKit MCP Key”）
4. 检查 音乐套件 并使用您的MusicKit标识符进行配置
5. 点击 继续 和 注册
6. 下载.p8文件 （你只能下载一次！）
7. 注意 密钥ID 显示在页面上

3.查找您的团队ID

您的团队ID位于Apple Developer门户的右上角，或位于 会员详细信息.

安装

git clone <this-repo>
cd AppleMusicMCP
npm install
npm run build

配置

服务器是通过环境变量配置的：

授权

在使用库功能（播放列表、库歌曲、推荐）之前，您需要使用您的Apple Music帐户进行授权：

APPLE_MUSIC_TEAM_ID=YOUR_TEAM_ID \
APPLE_MUSIC_KEY_ID=YOUR_KEY_ID \
APPLE_MUSIC_PRIVATE_KEY_PATH=/path/to/AuthKey.p8 \
node dist/index.js auth

这将：

1. 打开浏览器到本地授权页面
2. 您点击“使用Apple Music授权”并使用您的Apple ID登录
3. 音乐用户令牌被捕获并存储在 ~/.apple-music-mcp/tokens.json
4. 代币有效期约为6个月

注： 目录搜索未经授权即可进行。只有图书馆/个人功能需要它。

添加到Claude桌面

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-music": {
      "command": "node",
      "args": ["/absolute/path/to/AppleMusicMCP/dist/index.js"],
      "env": {
        "APPLE_MUSIC_TEAM_ID": "YOUR_TEAM_ID",
        "APPLE_MUSIC_KEY_ID": "YOUR_KEY_ID",
        "APPLE_MUSIC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_XXXXXXXX.p8",
        "APPLE_MUSIC_STOREFRONT": "us"
      }
    }
  }
}

添加到克劳德代码

添加到您的克劳德代码设置(.claude/settings.json 或全局设置）：

{
  "mcpServers": {
    "apple-music": {
      "command": "node",
      "args": ["/absolute/path/to/AppleMusicMCP/dist/index.js"],
      "env": {
        "APPLE_MUSIC_TEAM_ID": "YOUR_TEAM_ID",
        "APPLE_MUSIC_KEY_ID": "YOUR_KEY_ID",
        "APPLE_MUSIC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_XXXXXXXX.p8"
      }
    }
  }
}

可用工具

search_music

搜索Apple Music目录。

• query （字符串，必填）：搜索词
• types （数组，可选）： ["songs", "albums", "artists", "playlists"] （默认：歌曲、专辑、艺术家）
• limit （数字，可选）：每种类型1-25个结果（默认值：10）
• storefront （字符串，可选）：国家代码

get_user_playlists

列出您的播放列表。

• limit （数字，可选）：1-100（默认值：25）
• offset （数字，可选）：分页偏移

get_playlist_tracks

从播放列表中获取曲目。

• playlist_id （字符串，必填）：播放列表ID
• limit （数字，可选）：1-100（默认值：100）
• offset （数字，可选）：分页偏移

create_playlist

创建新的播放列表。

• name （字符串，必填）：播放列表名称
• description （字符串，可选）：播放列表描述
• track_ids （string[]，可选）：初始添加的歌曲ID

add_tracks_to_playlist

将曲目添加到现有播放列表中。

• playlist_id （字符串，必填）：播放列表ID
• track_ids （string[]，必填）：要添加的歌曲ID（最多100个）

remove_tracks_from_playlist

从播放列表中删除曲目（Apple API支持有限）。

• playlist_id （字符串，必填）：播放列表ID
• track_ids （string[]，必填）：要删除的歌曲ID

get_library_songs

从您的资料库中获取歌曲。

• limit （数字，可选）：1-100（默认值：25）
• offset （数字，可选）：分页偏移

get_recently_played

获取最近播放的曲目。

• limit （数字，可选）：1-10（默认值：10）

get_recommendations

获取个性化音乐推荐。

• limit （数量，可选）：1-30个推荐组（默认值：10）

示例用法

配置后，您可以向Claude询问以下问题：

• “在Apple Music上搜索泰勒·斯威夫特的歌曲”
• “显示我的Apple Music播放列表”
• “创建一个名为“Road Trip”的新播放列表，其中包含一些摇滚歌曲”
• “我最近在听什么？”
• “获取我的音乐推荐”
• “将歌曲《波西米亚狂想曲》添加到我的公路旅行播放列表中”

故障排除

“需要音乐用户令牌”

运行身份验证流： node dist/index.js auth

“身份验证失败（401）”

您的开发人员令牌可能无效。检查您的团队ID、密钥ID和私钥路径。

“禁止访问（403）”

您的音乐用户令牌可能已过期（有效期约为6个月）。重新运行： node dist/index.js auth

浏览器中未加载身份验证页面

确保端口7829未被使用。使用以下命令设置其他端口 APPLE_MUSIC_AUTH_PORT.

“remove_tracks_from_playlist”不起作用

这是已知的Apple Music API限制。API对播放列表曲目的DELETE支持有限。使用解决方法：使用要保留的曲目创建一个新的播放列表。

发展

npm run dev    # Run with tsx (no build needed)
npm run build  # Compile TypeScript
npm start      # Run compiled version

建筑

• 运输： stdio（通过stdin/stdout的JSON-RPC）
• API 直接REST调用 api.music.apple.com/v1/
• 认证： ES256 JWT开发者令牌+基于浏览器的MusicKit JS用户令牌
• 缓存： 具有每个端点TTL的内存中
• 错误处理： 键入错误，并提供有用的消息和速率限制的重试逻辑