tidal-mcp

🎵 TIDAL MCP（社区维护的分支）

📢 主动维护公告：这是 yuhuacheng/tidal-mcp 的社区分支，目前正积极维护。 原始仓库自 2025 年 5 月以来似乎已无人维护。欢迎在此提交贡献、问题和 PR！

大多数音乐平台都会提供推荐功能——每日发现、热门艺人、新品上架等——但即使采用了最先进的系统，推荐结果往往仍显得过于“笼统”。我希望能获得更个性化、更能结合上下文的推荐。

使用 TIDAL MCP，你可以提出这样的要求：

“根据我最近收藏的 10 首歌曲，查找相似曲目——但只要近几年的。”

“帮我找一些与这个播放列表中的歌曲相似，但节奏更慢、更偏原声的曲目。”

大模型会根据你的输入筛选和整理结果，通过 TIDAL 的 API 查找相似曲目，并直接在你的账户中创建新播放列表。

🆕 此分支的新变化

这个社区分支相比原始版本有多项重要改进：

• ✅ Docker 支持：提供完整的 Docker 和 docker-compose 配置，便于部署
• ✅ 搜索功能：可搜索 TIDAL 上的曲目、专辑、艺人和播放列表
• ✅ 分页：获取大型播放列表中的所有曲目（不再受限于 50 首！）
• ✅ 完整的播放列表编辑功能：添加、移除、重新排序曲目并更新元数据
• ✅ 重构代码库：文件体积缩小约 60%，组织更合理，也更易于维护
• ✅ DRY 分页助手：在所有端点中复用分页工具

查看完整更新日志并参与贡献：https://github.com/ibeal/tidal-mcp

功能

• 🌟 音乐推荐：根据你的聆听历史 以及自定义条件 获取个性化曲目推荐
• 🎵 完整的播放列表管理：创建、查看、编辑和删除播放列表，并拥有完整控制权
• 🔍 高级搜索：搜索曲目、专辑、艺人和播放列表
• 📄 智能分页：自动获取任意大小播放列表中的所有曲目
• 🎛️ 播放列表编辑：添加、移除、重新排序曲目并更新元数据
• 🐳 可用于 Docker：支持 Docker 和 docker-compose，便于部署
• 🔐 OAuth 身份验证：通过安全的浏览器登录流程登录 TIDAL

快速开始

前提条件

• Python 3.10+ 或 Docker
• uv（Python 包管理器）——仅非 Docker 安装需要
• TIDAL 订阅

安装

选项 1：Docker（推荐）

1. 克隆此仓库：

   git clone https://github.com/ibeal/tidal-mcp.git
   cd tidal-mcp
   

2. 使用 Docker Compose 构建并运行：

   docker-compose up -d
   

   或直接使用 Docker：

   docker build -t tidal-mcp .
   docker run -d -p 5050:5050 --name tidal-mcp tidal-mcp
   

   服务将在 http://localhost:5050 上运行。

3. 如需自定义端口，请编辑 docker-compose.yml 中的 TIDAL_MCP_PORT 环境变量，或将其传递给 docker run：

   docker run -d -p 5100:5100 -e TIDAL_MCP_PORT=5100 --name tidal-mcp tidal-mcp
   

选项 2：本地 Python 安装

1. 克隆此仓库：

   git clone https://github.com/ibeal/tidal-mcp.git
   cd tidal-mcp
   

2. 创建虚拟环境，并使用 uv 安装依赖：

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 安装 pyproject.toml 文件中的所有依赖：

   uv pip install --editable .
   

   这会安装 pyproject.toml 文件中定义的所有依赖，并以开发模式配置项目。

MCP 客户端配置

Claude Desktop 配置

要将此 MCP 服务添加到 Claude Desktop，需要更新 MCP 配置文件。

选项 1：Docker 配置（如果使用 Docker）

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network",
        "host",
        "-v",
        "/tmp:/tmp",
        "tidal-mcp"
      ],
      "env": {
        "TIDAL_MCP_PORT": "5050"
      }
    }
  }
}

设置：

1. 构建 Docker 镜像：

   docker build -t tidal-mcp .
   

2. 使用 TIDAL 进行身份验证（运行一次即可）：

   docker-compose -f docker-compose.auth.yml run --rm tidal-auth
   

   你会在输出中看到 OAuth URL：

   ============================================================
   TIDAL LOGIN REQUIRED
   Please open this URL in your browser:
   
   https://link.tidal.com/XXXXX
   
   Expires in 300 seconds
   ============================================================
   

   在浏览器中打开该 URL，登录 TIDAL，会话将保存到 /tmp/tidal-session-oauth.json。

3. 更新 Claude Desktop 配置（参见上文），然后重启 Claude Desktop。

配置详情：

• --network host - 允许容器直接使用主机的网络
• -v /tmp:/tmp - 挂载主机的 /tmp 目录，以便 TIDAL 会话在容器重启后仍然保留

要使用自定义端口：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network",
        "host",
        "-v",
        "/tmp:/tmp",
        "-e",
        "TIDAL_MCP_PORT=5100",
        "tidal-mcp"
      ]
    }
  }
}

选项 2：本地 Python 配置（如果不使用 Docker）

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "/path/to/your/uv",
      "env": {
        "TIDAL_MCP_PORT": "5100"
      },
      "args": [
        "run",
        "--with",
        "requests",
        "--with",
        "mcp[cli]",
        "--with",
        "flask",
        "--with",
        "tidalapi",
        "mcp",
        "run",
        "/path/to/your/project/tidal-mcp/mcp_server/server.py"
      ]
    }
  }
}

Claude Desktop 中 MCP 配置的示例截图：

Cursor 配置

Cursor 用户请将此配置添加到 MCP 设置文件（~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "/path/to/your/project/tidal-mcp/.venv/bin/python",
      "env": {
        "TIDAL_MCP_PORT": "5100"
      },
      "args": ["/path/to/your/project/tidal-mcp/start_mcp.py"]
    }
  }
}

重要提示：将 /path/to/your/project/tidal-mcp 替换为项目目录的实际路径。

在 Cursor 中安装 MCP 配置的步骤

1. 在 ~/.cursor/mcp.json 创建或编辑 MCP 配置文件
2. 添加上方的 TIDAL Integration 配置
3. 更新路径，使其与项目的实际位置相符
4. 保存文件
5. 重启 Cursor 以加载新的 MCP 服务

在 Claude Desktop 中安装 MCP 配置的步骤

1. 打开 Claude Desktop
2. 前往 Settings > Developer
3. 点击“Edit Config”
4. 粘贴修改后的 JSON 配置
5. 保存配置
6. 重启 Claude Desktop

推荐的提示词起始语

配置完成后，你可以通过向大模型提问来使用 TIDAL 账户，例如：

• “推荐一些与此播放列表中的歌曲相似，但节奏更慢、更偏原声的歌曲。”
• “根据我的热门曲目创建一个播放列表，但以轻松、适合深夜聆听的氛围为主。”
• “查找与播放列表 XYZ 中这些歌曲相似的歌曲，但语言不要是英语。”

💡 你还可以让模型：

• 使用更多曲目作为种子，以拓宽灵感范围。
• 如果想要更长的播放列表，就提供更多推荐。
• 或者，如果你不喜欢某个播放列表，也可以删除它——完全没关系！

可用工具

TIDAL MCP 集成提供以下工具：

身份验证与核心功能

• tidal_login：通过浏览器登录流程向 TIDAL 进行身份验证
• get_favorite_tracks：从 TIDAL 获取你收藏的曲目
• recommend_tracks：获取个性化音乐推荐

播放列表管理

• create_tidal_playlist：在你的 TIDAL 账户中创建新的播放列表
• get_user_playlists：列出你在 TIDAL 上的所有播放列表
• get_playlist_tracks：获取指定播放列表中的所有曲目（自动分页）
• delete_tidal_playlist：从你的 TIDAL 账户中删除播放列表
• add_tracks_to_playlist：向现有播放列表添加曲目
• remove_tracks_from_playlist：按 ID 或位置索引移除曲目
• update_playlist_metadata：更新播放列表标题和／或描述
• reorder_playlist_tracks：调整播放列表中曲目的位置

搜索与发现

• search_tidal：搜索 TIDAL 上的所有内容类型
• search_tracks：专门搜索曲目／歌曲
• search_albums：专门搜索专辑
• search_artists：专门搜索艺人
• search_playlists：专门搜索播放列表

许可证

MIT 许可证

贡献

这是一个积极维护的社区分支。欢迎贡献！

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

致谢

原始项目：

• yuhuacheng/tidal-mcp - 原始 TIDAL MCP 实现

贡献者：

• ra100 - 搜索功能特性

库和框架：

• Model Context Protocol (MCP)
• TIDAL Python API