使用说明
MCP苹果音乐服务器
用于在macOS上控制Apple Music的MCP服务器。
概述
该项目提供了 模型上下文协议（MCP） 允许您在macOS设备上控制Apple Music应用程序的服务器。它通过执行AppleScript命令来工作(osascript)引擎盖下。
服务器是用TypeScript构建的，使用Express.js来处理HTTP连接和 @modelcontextprotocol/sdk 用于MCP通信。
注： 此服务器设计为直接在macOS机器上运行，因为它依赖于 osascript 与Apple Music互动。
特性
- 控制Apple Music播放（播放、暂停、下一首曲目）。
- 调整音量。
- 在库中搜索歌曲、专辑和艺术家。
- 搜索并立即播放歌曲。
- 获取当前播放的曲目名称。
- 将功能作为MCP工具公开。
需求
- 操作系统：macOS
- 运行时：Node.js v20+
⚙️ 设置和安装
-
克隆存储库：
git clone https://github.com/samwang0723/mcp-applemusic.git cd mcp-applemusic -
安装依赖项：
npm install -
配置环境变量： 创建一个
.env项目根目录中的文件。如果提供了示例，您可以复制它，也可以从头开始创建它。# The port the server will listen on (default: 3000) PORT=3000 # The logging level (e.g., 'debug', 'info', 'warn', 'error') (default: 'info') LOG_LEVEL=info
🚀 用法
发展
以热重新加载的开发模式运行服务器（感谢 tsx):
npm run dev
生产
要构建和运行用于生产的服务器，请执行以下操作：
# 1. Build the TypeScript source code
npm run build
# 2. Start the server
npm start
运行后，服务器将在以下时间可用 http://localhost:3000 （或您配置的 PORT).
🛠️ 可用工具
服务器提供以下工具供MCP客户端使用：
| 工具名称 | 描述 | 参数 |
|---|---|---|
apple-music-set-volume |
调整Apple Music音量 | level：数字（0-10） |
apple-music-next-track |
播放下一首曲目 | 无 |
apple-music-pause |
暂停音乐播放 | 无 |
apple-music-play |
恢复音乐播放 | 无 |
apple-music-search-album |
按专辑搜索曲目 | album：string |
apple-music-search-and-play |
搜索并播放歌曲 | song：string |
apple-music-search-song |
搜索特定歌曲 | song：string |
apple-music-search-artist |
按艺术家搜索曲目 | artist：string |
apple-music-get-current-track |
获取当前播放的曲目 | 无 |
🔌 API终点
服务器公开以下HTTP端点：
GET /health：健康检查端点。退货{ "status": "ok", "service": "mcp-applemusic-server" }./mcp（GET、POST、DELETE）：MCP通信的主要端点。
🐳 码头工人
A. Dockerfile 包含在这个项目中。您可以使用以下方法构建Docker镜像：
docker build -t mcp-applemusic .
但是，请注意以下几点 临界极限:
⚠️ Docker容器将无法正常运行。 ⚠️
服务器依赖于 osascript 控制Apple Music，这是一个特定于macOS的实用程序。标准Docker镜像是基于Linux的，不包括此实用程序。当调用任何Apple Music工具时，在提供的Docker容器中运行服务器都会导致错误。
这 Dockerfile 应该被视为通用Node.js应用程序的启动模板，并且需要基于macOS的环境才能成功运行。
🔬 开发脚本
npm run lint：使用ESLint抓取代码。npm run lint:fix：自动修复掉毛问题。npm test：使用Jest运行测试（需要创建测试文件）。
