AI导哈

Apple Music API服务器与CLI工具

一个通过STDIO暴露Apple Music API操作（目录、库、推荐、播放列表管理和实用程序传递）的MCP服务器，以及一个用于直接终端访问的CLI工具。

  • by bastianX6
  • Swift
  • 本地部署
  • 更新于
在 GitHub 查看 bastianX6/apple-music-mcp-server

使用说明

苹果音乐MCP服务器（Swift）+命令行界面

一个MCP服务器，使用MCP Swift SDK和奇偶校验CLI通过STDIO公开Apple Music API操作（目录、库、推荐、播放列表管理和实用程序传递）(apple-music-tool)用于直接终端接入。在macOS 13+和Linux上的Swift 6（x86_64，Swift.org工具链）上进行了测试。

安装

使用install.sh（推荐）

  • 从repo根目录：
    bash ./install.sh
  • 脚本构建 两者 apple-music-mcp 和 apple-music-tool 发布并安装到 ~/.local/bin/ （如果缺少，则创建目录）。
  • 在Linux上，确保安装了Swift工具链（Swift 6）和基本构建工具；剧本的工作原理是一样的。

手动安装（基于源代码）

  1. 从Swift包目录（repo根目录），内建版本：
    swift build -c release --product apple-music-mcp --product apple-music-tool
  2. 将二进制文件复制到bin路径：
    mkdir -p "$HOME/.local/bin"
install -m 755 .build/release/apple-music-mcp "$HOME/.local/bin/apple-music-mcp"
install -m 755 .build/release/apple-music-tool "$HOME/.local/bin/apple-music-tool"

配置

配置文件

  • 服务器仅从以下位置读取凭据 ~/Library/Application Support/apple-music-mcp/config.json （强制执行0600权限）。
  • 用以下内容覆盖位置 --config /path/to/config.json 在任一 run 或 setup 子命令。
  • 如果文件丢失， apple-music-mcp 退出时出现错误，提醒您运行 setup.

所需的环境变量 setup

  • APPLE_MUSIC_TEAM_ID
  • APPLE_MUSIC_MUSICKIT_ID
  • APPLE_MUSIC_PRIVATE_KEY （内联PEM）

这 setup 子命令仅根据这些环境变量以及您提供的音乐用户令牌（CLI或浏览器帮助程序）构建配置文件。缺少env变量现在导致 setup 快速失败。

用户令牌设置（适用于两个二进制文件）

  • CLI模式（持久化现有令牌）：
    APPLE_MUSIC_TEAM_ID="<team>" \
APPLE_MUSIC_MUSICKIT_ID="<kid>" \
APPLE_MUSIC_PRIVATE_KEY="$(cat /path/to/AuthKey.p8)" \
swift run apple-music-mcp setup --token "<user-token>"
swift run apple-music-tool setup --token "<user-token>"
# Using the installed binary
APPLE_MUSIC_TEAM_ID="<team>" \
APPLE_MUSIC_MUSICKIT_ID="<kid>" \
APPLE_MUSIC_PRIVATE_KEY="$(cat /path/to/AuthKey.p8)" \
$HOME/.local/bin/apple-music-mcp setup --token "<user-token>"
$HOME/.local/bin/apple-music-tool setup --token "<user-token>"
  • 浏览器助手模式（本地服务器+MusicKit流）：
    APPLE_MUSIC_TEAM_ID="<team>" \
APPLE_MUSIC_MUSICKIT_ID="<kid>" \
APPLE_MUSIC_PRIVATE_KEY="$(cat /path/to/AuthKey.p8)" \
swift run apple-music-mcp setup --serve --port 3000
swift run apple-music-tool setup --serve --port 3000
# Using the installed binary
APPLE_MUSIC_TEAM_ID="<team>" \
APPLE_MUSIC_MUSICKIT_ID="<kid>" \
APPLE_MUSIC_PRIVATE_KEY="$(cat /path/to/AuthKey.p8)" \
$HOME/.local/bin/apple-music-mcp setup --serve --port 3000
$HOME/.local/bin/apple-music-tool setup --serve --port 3000
    这将打开您的默认浏览器（通过 open 在macOS或 xdg-open 如果Linux上可用）进行Apple Music授权，并写入每个应用程序的配置文件 0600 收到令牌后的权限（包括团队ID、MusicKit ID和私钥（如果env提供））。
  • 或者，如果您已经有一个用户令牌（每个应用程序路径），请在配置文件中放置一个现有的用户令牌。

运行服务器

  • 使用源代码（开发工作流）：
    swift run apple-music-mcp
  • 使用已安装的二进制文件（之后 install.sh 或手动安装）：
    $HOME/.local/bin/apple-music-mcp

两个命令均已读取 ~/Library/Application Support/apple-music-mcp/config.json （或通过传递的文件 --config)并在运行时忽略环境变量。

运行CLI

  • 使用源代码（无需安装）：
    swift run apple-music-tool <subcommand> [options]
  • 使用已安装的二进制文件：
    $HOME/.local/bin/apple-music-tool <subcommand> [options]

使用 --beautify 漂亮地打印JSON。看 docs/tool_cli_overview.md 和 docs/tool_cli_reference.md 用于子命令列表和参数。为了快速检查，您可以通过以下方式运行CLI swift run 而无需构建发布二进制文件。

测试

从Swift包目录（repo根目录）：

swift test

刀具表面（混合型）

该仓库为MCP和CLI使用混合工具界面。

真相来源：

  • docs/hybrid_tool_spec.md 用于预期的工具表面。
  • docs/hybrid_tool_endpoint_mapping.md 用于完整的端点到工具映射。
  • docs/apple_music_api_endpoints.md 从Apple文档中导出的Apple Music API端点列表。
  • docs/API_LIMITATIONS.md 用于已知的API约束和404/405行为。
  • docs/hybrid_tool_smoke_prompts.md 用于MCP烟雾测试。
  • docs/hybrid_tool_cli_smoke_prompts.md 对于CLI烟雾测试，使用 swift run apple-music-tool.
  • docs/tool_cli_overview.md, docs/tool_cli_reference.md, docs/tool_cli_checklist.md, docs/tool_cli_index.md 用于CLI奇偶校验文档。

指导：

  • 将基于意图的工具（搜索、图表、目录查找、库列表、推荐、播放列表管理）用于常见的工作流程。
  • 使用通用工具进行关系、视图和键入id查询。
  • 保持 generic_get 仅作为新端点或未映射端点的后备方案。

相关 MCP