苹果音乐MCP服务器
与Apple Music集成的MCP（模型上下文协议）服务器，允许Claude和其他MCP客户端搜索目录、管理播放列表和访问您的库。
特性
- 搜索 Apple Music目录（歌曲、专辑、艺术家、播放列表）
- 列表 您的播放列表并浏览其曲目
- 创建 带有可选初始曲目的新播放列表
- 添加曲目 到现有播放列表
- 浏览 您的库歌曲
- 视图 最近播放的曲目
- 获取 个性化推荐
先决条件
- Node.js 18+
- 一 Apple 开发者计划 会员资格
- MusicKit标识符和私钥
苹果开发者设置
1.创建MusicKit标识符
- 首选 Apple开发者>证书、标识符和配置文件
- 点击 + 注册新的标识符
- 选择 音乐套件ID （或 媒体ID)
- 输入描述（例如“MCP服务器”）和标识符（例如。，
com.yourname.musicmcp) - 点击 继续 和 注册
2.创建MusicKit私钥
- 首选 苹果开发者>密钥
- 点击 + 创建新密钥
- 命名它（例如，“MusicKit MCP Key”）
- 检查 音乐套件 并使用您的MusicKit标识符进行配置
- 点击 继续 和 注册
- 下载.p8文件 （你只能下载一次！）
- 注意 密钥ID 显示在页面上
3.查找您的团队ID
您的团队ID位于Apple Developer门户的右上角，或位于 会员详细信息.
安装
git clone
cd AppleMusicMCP
npm install
npm run build配置
服务器是通过环境变量配置的：
| 变量 | 必填 | 描述 |
|---|---|---|
APPLE_MUSIC_TEAM_ID | 是 | 您的Apple开发者团队ID |
APPLE_MUSIC_KEY_ID | 是 | 您的MusicKit密钥ID（来自您创建的密钥） |
APPLE_MUSIC_PRIVATE_KEY_PATH | 是 | 通往您的绝对之路 .p8 私钥文件 |
APPLE_MUSIC_STOREFRONT | 否 | ISO 3166 alpha-2国家代码（默认值： us) |
APPLE_MUSIC_CONFIG_DIR | 否 | 配置目录路径（默认： ~/.apple-music-mcp/) |
APPLE_MUSIC_AUTH_PORT | 无 | 身份验证服务器端口（默认值： 7829) |
授权
在使用库功能（播放列表、库歌曲、推荐）之前，您需要使用您的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这将：
- 打开浏览器到本地授权页面
- 您点击“使用Apple Music授权”并使用您的Apple ID登录
- 音乐用户令牌被捕获并存储在
~/.apple-music-mcp/tokens.json - 代币有效期约为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（字符串，必填）：播放列表IDlimit（数字，可选）：1-100（默认值：100）offset（数字，可选）：分页偏移
create_playlist
创建新的播放列表。
name（字符串，必填）：播放列表名称description（字符串，可选）：播放列表描述track_ids（string\[\]，可选）：初始添加的歌曲ID
add_tracks_to_playlist
将曲目添加到现有播放列表中。
playlist_id（字符串，必填）：播放列表IDtrack_ids（string\[\]，必填）：要添加的歌曲ID（最多100个）
remove_tracks_from_playlist
从播放列表中删除曲目（Apple API支持有限）。
playlist_id（字符串，必填）：播放列表IDtrack_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的内存中
- 错误处理： 键入错误，并提供有用的消息和速率限制的重试逻辑