内容
# MixCraft
允许 Claude 访问您的音乐库。MixCraft 是一个托管的 MCP 服务器，连接 Claude 到 Apple Music，让 Claude 可以搜索您的库、创建播放列表，并随着时间的推移了解您的音乐品味。
**[mixcraft.app](https://mixcraft.app)** — 60 秒即可设置。
> **Spotify 支持**：Spotify 的开发者计划限制应用程序必须手动管理允许列表，无法为公共分发扩展，因此托管的 `mixcraft.app` 部署仅支持 Apple Music。完整的 Spotify 集成（适配器、OAuth、刷新逻辑）存放在此仓库中，位于单个部署时标志后面 — 您可以 fork 它，注册自己的 Spotify 开发者应用程序，并为自己和几位朋友自行托管。参见 [docs/SELF-HOSTING.md](docs/SELF-HOSTING.md)。
## 快速入门
### 1. 连接您的音乐
访问 [mixcraft.app](https://mixcraft.app)，登录并连接 Apple Music。（启用 `enableSpotify` 的自行托管版本也可以在此处连接 Spotify。）
### 2. 将 MixCraft 添加到 Claude
#### claude.ai / 桌面端
**连接器（推荐 claude.ai）** — 无需 API 密钥：
1. 进入 **自定义 > 连接器 > + > 添加自定义连接器**
2. 填写：
- **名称**：`Mixcraft`
- **远程 MCP 服务器 URL**：`https://mcp.mixcraft.app/mcp`
3. 展开 **高级设置** 并添加：
- **OAuth 客户端 ID**：`FLECRN3FqkNiXtGI`
4. 点击 **添加**，然后使用您的 MixCraft 帐户登录以授权
连接后，MixCraft 将在您的连接器中出现，并带有所有可用的工具：
**插件** — 包括智能整理的播放列表助手技能：
1. 点击提示框旁边的 **+** 按钮并选择 **插件**
2. 选择 **添加插件** 以打开插件浏览器
3. 找到 **MixCraft** 并安装它（选择 **用户**、**项目** 或 **本地** 范围）
如果市场未列出，请先添加它：运行 `/plugin`，进入 **市场** 选项卡，然后添加 `schuettc/mixcraft-app`。
在您的 shell 配置文件（`.bashrc`、`.zshrc` 等）中设置您的 API 密钥：
```bash
export MIXCRAFT_API_KEY="mx_your_key_here"
```
#### Claude 代码 CLI
**插件（推荐）** — 包括播放列表助手技能：
```bash
/plugin marketplace add schuettc/mixcraft-app
/plugin install mixcraft@mixcraft-app
/reload-plugins
```
在您的 shell 配置文件（`.bashrc`、`.zshrc` 等）中设置您的 API 密钥：
```bash
export MIXCRAFT_API_KEY="mx_your_key_here"
```
**仅 MCP** — 工具无播放列表助手技能：
将以下内容添加到您的项目的 `.mcp.json`（用 [mixcraft.app](https://mixcraft.app) 中的您的 API 密钥替换 `mx_your_key_here`）：
```json
{
"mcpServers": {
"mixcraft": {
"command": "npx",
"args": ["-y", "mixcraft-app@latest"],
"env": {
"MIXCRAFT_API_KEY": "mx_your_key_here"
}
}
}
}
```
#### Claude 桌面端
将以下内容添加到您的配置文件（用 [mixcraft.app](https://mixcraft.app) 中的您的 API 密钥替换 `mx_your_key_here`）：
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"mixcraft": {
"command": "npx",
"args": ["-y", "mixcraft-app@latest"],
"env": {
"MIXCRAFT_API_KEY": "mx_your_key_here"
}
}
}
}
```
### 3. 使用它
只需询问 Claude 关于音乐：
- "为我创建一个长途驾驶的播放列表"
- "我最近一直在听什么？"
- "在我的运动播放列表中添加一些新歌曲"
- "给我找一些类似 Radiohead 但更电子的音乐"
- "我需要专注于编码的音乐"
## 您将获得
### MCP 工具
工具根据您连接的服务注册。当 Apple Music 和 Spotify 都连接时，工具带有前缀（`apple_music_*`、`spotify_*`），以便 Claude 知道使用哪种服务。
**共享工具**（适用于两种服务）：
| 工具 | 描述 |
|------|-------------|
| `search_catalog` | 搜索歌曲、专辑和艺术家 |
| `list_playlists` | 列出您的库播放列表 |
| `get_playlist_tracks` | 获取播放列表中的曲目 |
| `create_playlist` | 创建新的播放列表 |
| `add_tracks` | 将曲目添加到播放列表 |
| `get_recently_played` | 最近的聆听历史 |
| `get_library_songs` | 您库中的歌曲 |
| `add_to_library` | 将歌曲或专辑添加到您的库 |
**仅限 Spotify 工具**（仅在连接 Spotify 时注册；需要使用 `enableSpotify=true` 的自行托管部署）：
| 工具 | 描述 |
|------|-------------|
| `remove_playlist` | 删除（取消关注）播放列表 |
| `remove_tracks_from_playlist` | 从播放列表中删除特定曲目 |
| `reorder_playlist_tracks` | 重新排序播放列表中的曲目 |
| `update_playlist` | 重命名、更新描述或更改可见性 |
| `remove_from_library` | 从您的库中删除歌曲或专辑 |
| `get_top_items` | 通过聆听历史记录获取您的热门艺术家或曲目 |
### 播放列表助手技能
插件包括一项技能，教会 Claude 成为一个深思熟虑的音乐伴侣：
- **了解您的品味** — 在推荐任何内容之前检查您最近播放的音乐和库
- **有意策划** — 创建具有能量弧、流派桥梁和熟悉的最爱和新发现的混合播放列表
- **记住偏好** — 在 `.claude/mixcraft.local.md` 中存储您的喜欢、不喜欢和聆听上下文，以便未来会话在此基础上继续
- **服务感知** — 了解 Apple Music 和 Spotify 之间的区别（例如，Apple Music 播放列表无法通过 API 删除，Spotify 可以）并相应地调整行为
## 工作原理
MixCraft 作为托管服务运行，因此您无需管理开发者凭证或运行任何服务器。
```
claude.ai <--HTTPS--> MixCraft API <--REST--> Apple Music / Spotify
Claude 代码 / 桌面端 <--stdio--> CLI (npx mixcraft-app) <--HTTPS--> MixCraft API
```
1. 您在 [mixcraft.app](https://mixcraft.app) 连接您的音乐服务 — 通过 MusicKit OAuth 连接 Apple Music，通过直接 OAuth 连接 Spotify
2. 您的音乐服务令牌使用 AWS KMS 加密并存储在 DynamoDB 中 — MixCraft 绝不会明文查看或存储令牌
3. **claude.ai** 通过 OAuth 2.0 与 PKCE 认证 — 登录一次，连接器处理其余部分
4. **Claude 代码 / 桌面端** 通过 API 密钥认证 — 在 [mixcraft.app](https://mixcraft.app) 创建一个并将其设置为 `MIXCRAFT_API_KEY`
5. 当 Claude 调用工具时，请求会命中 MixCraft API，它会解密您的令牌，调用相应的音乐服务，并返回结果
6. Spotify 令牌在过期时会自动刷新 — 无需重新授权
有关安全性和数据处理的更多详细信息，请参见 [SECURITY.md](docs/SECURITY.md)。
## 自行托管
想要 Spotify 支持或在您自己的 AWS 账户上运行整个堆栈？参见 [docs/SELF-HOSTING.md](docs/SELF-HOSTING.md) 以获取完整的演练 — Spotify 开发者应用程序注册、允许列表管理、机密种子和单个 CDK 上下文标志 (`-c enableSpotify=true`)，它开启所有功能。
## 许可证
MIT
