内容
# TIDAL MCP
[](https://www.npmjs.com/package/tidal-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://github.com/teobouancheau/tidal-mcp)
一个模型上下文协议（MCP）服务器，为 AI 助手提供对 TIDAL 音乐流媒体 API 的完全访问权限。搜索、浏览、管理播放列表、策划收藏和发现音乐。与 Claude Desktop、Claude Code、Claude.ai、Cursor 和任何 MCP 兼容的客户端一起使用。
支持 **本地**（stdio）和 **远程**（可流式 HTTP）传输。
## 功能
- **搜索**曲目、专辑、艺术家、播放列表和视频
- **浏览**流派、相似内容、艺术家广播和推荐
- **获取详情**曲目、专辑、艺术家、视频和播放列表
- **歌词和制作人员**任何曲目的
- **播放列表 CRUD** 创建、更新、删除、添加/删除项目
- **收藏管理** 添加/删除收藏（曲目、专辑、艺术家、播放列表、视频）
- **社交**关注/取消关注艺术家
- **发现**相似曲目、专辑、艺术家、视频、个性化混音
- **历史**查看和管理搜索历史
## 先决条件
- Node.js 20+
- TIDAL 开发者账户，包含 OAuth 客户端凭证（[developer.tidal.com](https://developer.tidal.com)）
## 安装
### 通过 npm（推荐）
```bash
npm install -g tidal-mcp
```
### 通过 npx（无需安装）
直接使用 npx 配置（参见配置部分）。
### 从源码
```bash
git clone https://github.com/teobouancheau/tidal-mcp.git
cd tidal-mcp
npm install
npm run build
```
## 配置
### 本地（stdio）-- Claude Desktop，Claude Code，Cursor
#### 快速入门，使用 npx
```json
{
"mcpServers": {
"tidal": {
"command": "npx",
"args": ["-y", "tidal-mcp"],
"env": {
"TIDAL_CLIENT_ID": "your_client_id",
"TIDAL_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
#### 使用全局安装
```bash
npm install -g tidal-mcp
```
```json
{
"mcpServers": {
"tidal": {
"command": "tidal-mcp",
"env": {
"TIDAL_CLIENT_ID": "your_client_id",
"TIDAL_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
#### 配置文件位置
| 客户端 | 路径 |
| ---------------------------- | ----------------------------------------------------------------- |
| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Desktop (Linux)** | `~/.config/Claude/claude_desktop_config.json` |
| **Claude Code** | `.mcp.json` 在您的项目中或 `~/.claude/settings.json` |
| **Cursor** | `.cursor/mcp.json` 在您的项目中 |
在更新配置后重启您的客户端。
### 远程（HTTP）-- Claude.ai，Claude Mobile，自定义连接器
```bash
npm run build
npm run start:http
```
服务器监听在 `PORT`（默认为 3000）。设置 `PORT` 环境变量以更改。
#### 通过 Claude.ai 连接
1. 进入 **设置 > 连接器**
2. 点击 **添加自定义连接器**
3. 输入您的服务器 URL（例如，`https://your-app.example.com/mcp`）
4. 点击 **添加**
## MCP 工具
### 搜索和发现（4 个工具）
#### search
在 TIDAL 上搜索曲目、专辑、艺术家、播放列表和视频。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `query` | 字符串 | 必需 | 搜索查询 |
| `countryCode` | 字符串 | "US" | ISO 3166-1 alpha-2 国家代码 |
| `type` | 字符串 | "all" | 过滤：all, tracks, albums, artists, playlists, videos |
| `limit` | 数字 | 10 | 每页结果数（1-50） |
| `cursor` | 字符串 | - | 分页光标 |
| `explicitFilter` | 字符串 | "INCLUDE" | 包含或排除明确内容 |
#### search_suggestions
获取部分搜索查询的自动完成建议。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `query` | 字符串 | 必需 | 部分搜索查询 |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### get_genres
浏览 TIDAL 上所有可用的音乐流派。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### get_search_history
查看最近的搜索历史。
### 曲目（4 个工具）
#### get_track
获取 TIDAL 曲目的详细元数据。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 曲目 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
**返回：** 标题，艺术家，专辑，时长，ISRC，BPM，流行度，明确状态
#### get_lyrics
获取曲目的歌词。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `trackId` | 字符串 | 必需 | TIDAL 曲目 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### get_credits
获取曲目的制作人员。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `trackId` | 字符串 | 必需 | TIDAL 曲目 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
**返回：** 制片人，词曲作者，表演者，工程师
#### get_similar_tracks
查找与给定曲目相似的曲目。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `trackId` | 字符串 | 必需 | TIDAL 曲目 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
### 专辑（2 个工具）
#### get_album
获取专辑详情，包括曲目列表。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 专辑 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 曲目分页光标 |
**返回：** 标题，艺术家，类型（专辑/EP/单曲），发行日期，曲目列表，时长
#### get_similar_albums
查找与给定专辑相似的专辑。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `albumId` | 字符串 | 必需 | TIDAL 专辑 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
### 艺术家（7 个工具）
#### get_artist
获取艺术家详情，包括简介。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 艺术家 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### get_artist_albums
获取艺术家的唱片目录。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 艺术家 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
#### get_artist_tracks
获取艺术家的热门/流行曲目。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 艺术家 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
#### get_artist_videos
获取艺术家的音乐视频。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 艺术家 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
#### get_artist_radio
根据艺术家获取一个曲目广播电台。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 艺术家 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
#### get_similar_artists
查找与给定艺术家相似的艺术家。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 艺术家 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### follow_artist / unfollow_artist
关注或取消关注 TIDAL 上的艺术家。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `artistId` | 字符串 | TIDAL 艺术家 ID |
### 视频（2 个工具）
#### get_video
获取 TIDAL 视频的详细信息。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 视频 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### get_similar_videos
查找与给定视频相似的视频。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `videoId` | 字符串 | 必需 | TIDAL 视频 ID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 分页光标 |
### 播放列表（6 个工具）
#### get_playlist
获取播放列表详情，包括项目列表。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `id` | 字符串 | 必需 | TIDAL 播放列表 UUID |
| `countryCode` | 字符串 | "US" | 国家代码 |
| `cursor` | 字符串 | - | 项目分页光标 |
#### create_playlist
创建新的播放列表。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `name` | 字符串 | 必需 | 播放列表名称 |
| `description` | 字符串 | - | 播放列表描述 |
| `accessType` | 字符串 | "PUBLIC" | PUBLIC 或 UNLISTED |
#### update_playlist
更新现有的播放列表。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `id` | 字符串 | 播放列表 UUID（必需） |
| `name` | 字符串 | 新名称 |
| `description` | 字符串 | 新描述 |
| `accessType` | 字符串 | PUBLIC 或 UNLISTED |
#### delete_playlist
永久删除播放列表。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `id` | 字符串 | 播放列表 UUID |
#### add_playlist_items
将曲目或视频添加到播放列表（每次请求最多 20 个）。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `playlistId` | 字符串 | 播放列表 UUID |
| `items` | 数组 | 要添加的项目：`[{id, type: "tracks"|"videos"}]` |
| `positionBefore` | 字符串 | 在此位置之前插入（可选） |
#### remove_playlist_items
从播放列表中删除曲目或视频（每次请求最多 20 个）。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `playlistId` | 字符串 | 播放列表 UUID |
| `items` | 数组 | 要删除的项目：`[{id, type, itemId}]` |
### 用户和收藏（5 个工具）
#### get_user
获取用户配置文件。省略 ID 以获取当前已认证的用户。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `id` | 字符串 | 用户 ID（可选） |
#### get_collection
浏览用户的保存收藏（收藏）。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `collectionId` | 字符串 | 用户收藏 UUID |
| `type` | 字符串 | tracks, albums, artists, playlists, 或 videos |
| `cursor` | 字符串 | 分页光标 |
#### add_to_collection
将项目添加到用户的收藏（每次请求最多 20 个）。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `collectionId` | 字符串 | 收藏 UUID |
| `type` | 字符串 | tracks, albums, artists, playlists, 或 videos |
| `ids` | 字符串[] | 要添加的资源 ID |
#### remove_from_collection
从用户的收藏中删除项目（每次请求最多 20 个）。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `collectionId` | 字符串 | 收藏 UUID |
| `type` | 字符串 | tracks, albums, artists, playlists, 或 videos |
| `ids` | 字符串[] | 要删除的资源 ID |
#### get_recommendations
获取个性化的音乐推荐。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `userId` | 字符串 | 必需 | TIDAL 用户 ID |
| `type` | 字符串 | "discoveryMixes" | discoveryMixes, myMixes, 或 newArrivalMixes |
### 混音和历史（3 个工具）
#### get_mixes
获取个性化的 TIDAL 混音。
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `mixType` | 字符串 | 必需 | daily, discovery, 或 new-releases |
| `countryCode` | 字符串 | "US" | 国家代码 |
#### delete_search_history_entry
删除搜索历史中的特定条目。
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `id` | 字符串 | 搜索历史条目 ID |
## 使用示例
### 搜索和发现
```
"在 TIDAL 上搜索'Daft Punk'并获取他们热门曲目的详细信息"
```
### 探索艺术家
```
"谁是与 Radiohead 相似的艺术家？显示他们的唱片目录"
```
### 获取歌词和制作人员
```
"获取'Bohemian Rhapsody'的歌词和制作人员"
```
### 创建播放列表
```
"创建一个名为'Morning Jazz'的播放列表，并将这些曲目 ID 添加到其中"
```
### 音乐发现
```
"查找与这首歌相似的曲目，并从这位艺术家创建一个广播电台"
```
### 管理收藏
```
"将这些专辑添加到我的收藏中"
```
## 测试
```bash
npm test # 运行所有测试
npm run test:watch # 监视模式
npm run test:coverage # 覆盖率报告
```
## 开发
```bash
npm run dev # 监视模式
npm run build # 生产环境构建
npm run rebuild # 清洁并重建
npm start # 运行服务器（stdio）
npm run start:http # 运行服务器（HTTP）
npm run validate # 类型检查 + 校验 + 测试
```
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建一个功能分支
3. 运行测试（`npm run validate`）
4. 提交拉取请求
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 获取详细信息。
## 致谢
- [TIDAL](https://tidal.com) 获取音乐流媒体 API
- [Anthropic](https://anthropic.com) 获取模型上下文协议
---
<div align="center">
<strong>由 <a href="https://github.com/teobouancheau">teobouancheau</a> 构建</strong>
</div>
