使用说明

潮汐MCP

模型上下文协议（MCP）服务器，将人工智能助手连接到TIDAL音乐流API。搜索、管理播放列表、获取推荐，并通过Claude或Cursor控制您的TIDAL库。

运作原理

Claude Desktop / Cursor
        │
        │  MCP JSON-RPC over stdio
        ▼
  start_mcp.py          ← entry point + stdin proxy for clean shutdown
        │
  mcp_server/server.py  ← FastMCP app, 17 tool definitions
        │
        │  direct Python function calls
        ▼
  tidal_api/routes/     ← business logic (tracks, playlists, search, auth)
        │
  tidal_api/browser_session.py  ← tidalapi.Session wrapper
        │
        │  TIDAL REST API
        ▼
      TIDAL

工具调用使用来自磁盘的经过验证的OAuth会话，并在第一次成功加载后将其缓存在进程中。需要时，身份验证工具会使该缓存无效。MCP层调用相关 tidal_api/routes/ 函数直接返回。没有内部HTTP服务器，没有子进程，没有端口。

安装

先决条件

Python 3.10+ 或码头工人
紫外线 --仅需要本地（非Docker）安装
TIDAL订阅

会话目录

所有安装方法都将TIDAL OAuth会话存储在本地目录中。在继续之前创建一次：

macOS/Linux：

mkdir -p ~/.tidal-mcp

Windows（PowerShell）：

mkdir "$env:APPDATA\tidal-mcp"

这为您提供了一个固定、可预测的位置(~/.tidal-mcp/ 或 %APPDATA%\tidal-mcp\)MCP客户端通过绝对路径配置以下引用。

选项1：Docker Hub（最简单）

无需克隆或构建——直接从Docker Hub中提取预构建映像。支持amd64和arm64（苹果硅）。

拉取图像：
```
docker pull dragomirweb/tidal-mcp
```

通过TIDAL进行身份验证：

macOS/Linux：

docker run -it --rm \
  -v ~/.tidal-mcp:/app/session-data \
  -e TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json \
  dragomirweb/tidal-mcp \
  .venv/bin/python auth_cli.py

Windows（PowerShell）：

docker run -it --rm `
  -v "$env:APPDATA\tidal-mcp:/app/session-data" `
  -e TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json `
  dragomirweb/tidal-mcp `
  .venv/bin/python auth_cli.py

打开输出中显示的URL，登录TIDAL，会话将自动保存。

配置您的MCP客户端（请参阅 MCP客户端配置)并重新启动它。

选项2:Docker（从源代码构建）

克隆存储库：

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

塑造形象：

docker build -t dragomirweb/tidal-mcp .

通过TIDAL进行身份验证：

macOS/Linux：

docker run -it --rm \
  -v ~/.tidal-mcp:/app/session-data \
  -e TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json \
  dragomirweb/tidal-mcp \
  .venv/bin/python auth_cli.py

Windows（PowerShell）：

docker run -it --rm `
  -v "$env:APPDATA\tidal-mcp:/app/session-data" `
  -e TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json `
  dragomirweb/tidal-mcp `
  .venv/bin/python auth_cli.py

打开输出中显示的URL，登录TIDAL，会话将自动保存。

配置您的MCP客户端（请参阅 MCP客户端配置)并重新启动它。

选项3：本地Python

克隆存储库：

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

安装依赖项：
```
uv sync
```
配置您的MCP客户端（见下文）并重新启动。身份验证通过 tidal_login 工具——不需要单独的身份验证步骤。

MCP客户端配置

克劳德桌面

编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

Docker——macOS/Linux：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/.tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

替换 /Users/YOUR_USERNAME/.tidal-mcp 与你的绝对路径 ~/.tidal-mcp/ 目录（运行 echo ~/.tidal-mcp 得到它）。

Docker——Windows：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

替换 C:\Users\YOUR_USERNAME\AppData\Roaming\tidal-mcp 随着输出 echo %APPDATA%\tidal-mcp 在命令提示符中。

Docker是Windows上推荐的方法，特别是在使用WSL时。它避免了Windows和WSL Python环境之间的路径和venv兼容性问题。

本地-macOS/Linux：

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

本地--Windows（原生Python）：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "C:\\path\\to\\tidal-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\tidal-mcp\\start_mcp.py"]
    }
  }
}

需要安装本机Windows Python（不是WSL）。跑 uv sync 从Windows终端创建 .venv\Scripts\ 出来

光标

添加 ~/.cursor/mcp.json。配置与上面的Claude Desktop相同——使用与您的设置匹配的Docker或本地变体：

Docker——macOS/Linux：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/.tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

Docker——Windows：

{
  "mcpServers": {
    "TIDAL Integration": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

当地：

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

开源代码

添加 opencode.json 在项目根目录中，或 ~/.config/opencode/opencode.json 全球访问。请参阅 OpenCode MCP文档了解详情。

Docker——macOS/Linux：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tidal": {
      "type": "local",
      "command": [
        "docker", "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/.tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

替换 /Users/YOUR_USERNAME/.tidal-mcp 与你的绝对路径 ~/.tidal-mcp/ 目录。

Docker——Windows：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tidal": {
      "type": "local",
      "command": [
        "docker", "run", "-i", "--rm",
        "-v", "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

替换 C:\Users\YOUR_USERNAME\AppData\Roaming\tidal-mcp 随着输出 echo %APPDATA%\tidal-mcp.

本地-macOS/Linux：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tidal": {
      "type": "local",
      "command": ["/path/to/tidal-mcp/.venv/bin/python", "/path/to/tidal-mcp/start_mcp.py"]
    }
  }
}

本地--Windows：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tidal": {
      "type": "local",
      "command": ["C:\\path\\to\\tidal-mcp\\.venv\\Scripts\\python.exe", "C:\\path\\to\\tidal-mcp\\start_mcp.py"]
    }
  }
}

克劳德代码

使用 claude mcp add CLI命令。请参阅克劳德代码MCP文档了解详情。

Docker——macOS/Linux：

claude mcp add --transport stdio --scope user tidal-mcp -- \
  docker run -i --rm \
  -v /Users/YOUR_USERNAME/.tidal-mcp:/app/session-data \
  -e TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json \
  dragomirweb/tidal-mcp

替换 /Users/YOUR_USERNAME/.tidal-mcp 与你的绝对路径 ~/.tidal-mcp/ 目录。

Docker——Windows：

claude mcp add --transport stdio --scope user tidal-mcp -- ^
  docker run -i --rm ^
  -v C:\Users\YOUR_USERNAME\AppData\Roaming\tidal-mcp:/app/session-data ^
  -e TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json ^
  dragomirweb/tidal-mcp

替换 C:\Users\YOUR_USERNAME\AppData\Roaming\tidal-mcp 随着输出 echo %APPDATA%\tidal-mcp.

本地-macOS/Linux：

claude mcp add --transport stdio --scope user tidal-mcp -- \
  /path/to/tidal-mcp/.venv/bin/python /path/to/tidal-mcp/start_mcp.py

本地--Windows：

claude mcp add --transport stdio --scope user tidal-mcp -- ^
  C:\path\to\tidal-mcp\.venv\Scripts\python.exe C:\path\to\tidal-mcp\start_mcp.py

上述命令使用 --scope user 使服务器在所有项目中都可用。生成的配置存储在 ~/.claude.json:

{
  "mcpServers": {
    "tidal-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USERNAME/.tidal-mcp:/app/session-data",
        "-e", "TIDAL_SESSION_FILE=/app/session-data/tidal-session-oauth.json",
        "dragomirweb/tidal-mcp"
      ]
    }
  }
}

使用 --scope local （默认）用于每个项目配置，或 --scope project 创建共享 .mcp.json 在项目根中。

认证

首次使用TIDAL MCP时（或会话到期后），请让您的AI助手登录：

“让我登录TIDAL”

助理打来电话 tidal_login，它立即返回URL。在浏览器中打开URL并批准TIDAL授权。随后，助理进行了民意调查 tidal_check_login 自动，直到登录完成。

Docker用户 还可以在使用MCP客户端之前进行预身份验证（请参阅中的auth命令安装上文）。会话已保存到 ~/.tidal-mcp/tidal-session-oauth.json （macOS/Linux）或 %APPDATA%\tidal-mcp\tidal-session-oauth.json （Windows），并通过卷装载在容器重新启动时保持不变。

可用工具

认证

工具	说明
`tidal_login`	启动OAuth设备流。立即返回要打开的URL，或 `success` 如果已经过身份验证。
`tidal_check_login`	轮询浏览器OAuth是否已完成。跟在…后面叫 `tidal_login` 回报 `pending`.

跟踪和建议

工具	说明
`get_favorite_tracks(limit)`	检索您TIDAL收藏的曲目，按添加日期排序（最新曲目排在第一位）。
`recommend_tracks(track_ids, filter_criteria, limit_per_track, limit_from_favorite)`	通过TIDAL的曲目广播功能获得个性化推荐。来自明确曲目ID或自动获取收藏夹的种子。

播放列表管理

工具	说明
`create_tidal_playlist(title, track_ids, description)`	创建一个新的播放列表，并在一次通话中用曲目填充它。
`get_user_playlists`	列出所有播放列表，按上次更新时间排序。
`get_playlist_tracks(playlist_id, limit)`	从播放列表中获取所有曲目（自动分页，无大小限制）。
`delete_tidal_playlist(playlist_id)`	永久删除播放列表。
`add_tracks_to_playlist(playlist_id, track_ids)`	将曲目附加到现有播放列表。
`remove_tracks_from_playlist(playlist_id, track_ids, indices)`	通过TIDAL ID或基于0的位置索引删除轨迹。
`update_playlist_metadata(playlist_id, title, description)`	重命名播放列表或更新其描述。
`reorder_playlist_tracks(playlist_id, from_index, to_index)`	将轨迹移动到其他位置（基于0的索引）。

搜索与发现

工具	说明
`search_tidal(query, search_type, limit)`	搜索所有内容类型： `all`, `tracks`, `albums`, `artists`, `playlists`.
`search_tracks(query, limit)`	寻找足迹。
`search_albums(query, limit)`	搜索相册。
`search_artists(query, limit)`	寻找艺术家。
`search_playlists(query, limit)`	搜索播放列表。

环境变量

变量	默认值	描述
`TIDAL_SESSION_FILE`	`{tempdir}/tidal-session-oauth.json`	覆盖OAuth会话文件的路径。在运行多个实例或在进程之间的默认临时路径不同的系统上运行时很有用。

发展

设置

uv sync              # Install dependencies
uv run pytest tests/ -v   # Run the test suite (213 tests)

测试

该测试套件涵盖了所有17个MCP工具、所有19个路由功能和所有实用程序助手。测试使用 unittest.mock 嘲笑 tidalapi 和 mcp 在导入时，不需要TIDAL凭据或网络访问。

uv run pytest tests/ -v                          # Full suite
uv run pytest tests/test_routes.py -v            # Route function tests only
uv run pytest tests/test_server.py -v            # MCP tool tests only
uv run pytest tests/test_routes.py::TestComprehensiveSearchHappyPath -v  # Single class

测试文件	测试	封面
`test_routes.py`	112	所有路由功能（身份验证、曲目、播放列表、搜索）
`test_server.py`	65	所有17个MCP工具， `_call()`, `_get_session()`
`test_utils.py`	27	`bound_limit`, `fetch_all_items`, `format_track_data`
`test_browser_session.py`	6	`_ensure_https`, `BrowserSession.login_oauth_start`
`test_mcp_utils.py`	3	`SESSION_FILE` env-var覆盖逻辑

码头工人

更改代码后，重建映像：

docker build -t dragomirweb/tidal-mcp .

其他有用的命令

python -m compileall mcp_server/ tidal_api/   # Syntax-check all source files
uv run python auth_cli.py                     # Standalone OAuth CLI
uv run python start_mcp.py                    # Run the MCP server directly

项目结构

mcp_server/
  server.py          # FastMCP app, 17 @mcp.tool() definitions, session management
  utils.py           # SESSION_FILE path constant (env var controlled)

tidal_api/
  browser_session.py # BrowserSession (tidalapi.Session wrapper)
  utils.py           # format_track_data, bound_limit, fetch_all_items
  routes/
    auth.py          # handle_login_start, handle_login_poll, check_auth_status
    tracks.py        # get_user_tracks, get_recommendations, get_batch_track_recommendations
    playlists.py     # CRUD: create, get, delete, add/remove tracks, update, reorder
    search.py        # comprehensive_search + 4 type-specific search functions

tests/               # 213 unit tests (mocked deps, no credentials needed)
  conftest.py        # Centralized sys.modules mocking for tidalapi + mcp

许可证

MIT许可证

致谢

原始项目：

玉华城/潮汐mcp --TIDAL MCP的原始实现
ibeal/潮汐mcp --具有直接调用架构、搜索和Docker支持的社区分支

库和框架：

使用说明

潮汐MCP

运作原理

安装

先决条件

会话目录

选项1：Docker Hub（最简单）

选项2:Docker（从源代码构建）

选项3：本地Python

MCP客户端配置

克劳德桌面

光标

开源代码

克劳德代码

认证

可用工具

认证

跟踪和建议

播放列表管理

搜索与发现

环境变量

发展

设置

测试

码头工人

其他有用的命令

项目结构

许可证

致谢

相关 MCP

实时网络搜索服务

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

图像生成服务

滴滴出行MCP服务

AI开发助手