TIDAL MCP

TIDAL MCP — 面向 AI 助手的完整、安全优先型 TIDAL 服务

TIDAL MCP 将 Codex、Claude Desktop、Claude Code、Cursor 及其他兼容 stdio 的 Model Context Protocol 客户端连接到 TIDAL 账户。搜索曲库、分析播放列表、发现音乐、读取歌词、管理收藏、整理文件夹，并通过 122 个类型化 MCP 工具安全地创建或编辑播放列表。

**定位：**在 2026 年 9 月 4 日的评审中，这是对当前 GitHub 生态进行可复现评审后发现的最完整公开 TIDAL MCP 实现。此说法基于已注册工具的覆盖范围、结构化架构、变更安全性和自动化测试证据，而非仅凭营销宣传。请参阅带日期的对比。

为什么要开发这个 TIDAL MCP

大多数 TIDAL 集成只提供少量搜索和播放列表命令。TIDAL MCP 旨在为 AI Agent 提供完整的本地控制界面，同时将凭据和审批保留在你的设备上。

• **122 个可发现工具：**84 个读取工具、36 个变更预览工具，以及 2 个审批令牌提交工具。
• **广泛覆盖账户功能：**曲库、编辑精选页面、推荐、歌词、收藏、播放列表、文件夹、混音、图片和播放元数据。
• **安全写入：**默认关闭变更操作，始终需要先预览 → 明确批准 → 提交。
• **私密身份验证：**OAuth 会话数据绝不会通过 MCP 工具响应传输。
• **类型化且有界：**每项输入和输出都有架构、限制和 MCP 安全注解。
• **经过验证的质量：**语句和分支测试覆盖率均为 100%，还通过真实 stdio 握手测试，并可选择执行经过身份验证的只读冒烟测试。

AI 助手可以用 TIDAL 做什么？

自然地提出请求：

• “分析我完整的健身播放列表：艺人集中度、年代、重复曲目、时长和排序。”
• “找出与这三首歌曲相关的 20 首曲目，排除我的播放列表中已有的内容，并限制每位艺人最多两首曲目。”
• “比较一位艺人的专辑、EP、单曲、参与作品、热门曲目、简介和相关艺人。”
• “显示我收藏的专辑和播放列表，然后概述我的收藏分布情况。”
• “根据这些推荐准备一个新播放列表，并在执行任何操作前向我展示具体变更。”
• “将这些播放列表移到一个文件夹中，但在更改我的账户前先征求确认。”

请参阅实际工作流和提示词示例。

工具覆盖范围

功能	工具数	示例
身份验证、搜索、推荐	3	状态、多类型搜索、确定性的多种子推荐
目录、编辑内容、发现	54	曲目、专辑、艺人、视频、歌词、流派、Home、Explore、For You
收藏、播放列表、文件夹	22	收藏项、计数、播放列表项目、自有／公开播放列表、文件夹、混音
派生分析	3	完整播放列表收藏、播放列表摘要、播放列表比较
本地导出	2	将播放列表导出为 JSON 或 M3U，将摘要或比较结果导出为 JSON
精确变更预览	36	播放列表 CRUD、项目移动、可见性、收藏项、文件夹
审批令牌提交	2	通用提交和兼容的播放列表创建别名

表中合计为已注册的 122 个工具。此外还注册了 4 个 MCP 提示词（playlist-from-description、playlist review、discovery digest、library audit）；提示词用于指导如何使用这些工具，因此不计入工具数量。

所有列表操作都有数量限制并支持分页。每个结果都使用公开字段允许列表，确保 OAuth 令牌、请求客户端和内部会话数据不会进入模型上下文。完整映射见 API_COVERAGE.md。

快速开始

要求

• macOS 或 Linux；已在 macOS 上使用真实账户进行测试
• Node.js 18 或更高版本
• Python 3.11–3.13
• uv
• TIDAL 账户

1. 安装并进行身份验证

npx -y @sickn33/tidal-mcp auth

打开设备授权 URL，在 TIDAL 中批准访问，然后返回终端。会话存储在操作系统的私有应用数据目录中，而非代码仓库中。

随时检查或移除会话：

npx -y @sickn33/tidal-mcp auth --status
npx -y @sickn33/tidal-mcp auth --logout --yes

如需从源代码安装以进行开发：

git clone https://github.com/sickn33/tidal-mcp.git
cd tidal-mcp
uv sync
uv run tidal-auth

2. 连接 MCP 客户端

直接使用 npm；该软件包通过 uvx 在本地启动固定版本的 Python 实现：

{
  "mcpServers": {
    "tidal": {
      "command": "npx",
      "args": [
        "-y",
        "@sickn33/tidal-mcp"
      ]
    }
  }
}

重启或重新连接 MCP 客户端，然后询问：“检查我的 TIDAL 身份验证状态。”

启用安全账户写入

除非 MCP 进程收到以下内容，否则会禁用远程写入：

"env": {
  "TIDAL_MCP_ENABLE_WRITES": "1"
}

启用此标志并不会让变更自动执行。每项变更仍须经过以下三个明确步骤：

1. 名为 tidal_preview_* 的工具会将确切参数和目标元数据记录到私有的短时本地草稿中。
2. 助手向用户展示该预览。
3. 只有在获得批准后，tidal_commit_action 才会接受一次性令牌，并严格执行记录的操作。

成功的令牌重放会返回已存储的结果。令牌过期后会安全失败。为减少重复操作，结果不明确的失败写入会被锁定。破坏性预览会明确标注。

支持的 TIDAL 操作

• **搜索和查询：**曲目、专辑、艺人、播放列表、视频、混音、用户、条形码、ISRC。
• **曲目信息：**详情、电台、电台混音、歌词、播放元数据、临时账户范围 URL。
• **艺人和专辑：**唱片目录、EP 和单曲、客串作品、简介、评论、相关艺人、相似专辑、音质规格、封面图片和编辑页面。
• **发现：**Home、Explore、For You、流派、情绪、混音、视频、高清音质和本地流派中心。
• **编辑内容导航：**读取页面分类中的项目和链接，展开“显示更多／查看全部”部分，并打开页面链接以继续浏览首屏之后的内容。
• **收藏：**收藏曲目、专辑、艺人、播放列表、视频、混音、文件夹和计数。
• **播放列表：**元数据、曲目、混合项目、计数、图片、创建／编辑／删除／清空／合并、可见性，以及添加／移除／重新排序操作。
• **文件夹：**检查、创建、重命名、删除和移动收藏树中的项目。

该服务有意不下载媒体、绕过 DRM、公开原始 OAuth 方法，也不提供不受限制的私有端点代理。

配置

变量	默认值	含义
TIDAL_MCP_ENABLE_WRITES	0	允许使用审批令牌提交列入允许列表的账户变更
TIDAL_MCP_DATA_DIR	OS 应用程序数据目录	会话和草稿根目录
TIDAL_MCP_SESSION_FILE	<data-dir>/session.json	覆盖 OAuth 会话路径
TIDAL_MCP_DRAFT_TTL_SECONDS	900	审批有效期，介于 60 到 3600 秒之间
TIDAL_MCP_EXPORT_DIR	<data-dir>/exports	tidal_export_playlist 的写入位置；会以私有权限创建

在支持 POSIX 权限的系统上，新的私有目录使用 0700 模式，敏感文件使用 0600 模式。不会擅自改写现有自定义父目录的权限。

已验证的质量

uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pytest --cov=tidal_mcp --cov-report=term-missing
uv run python scripts/smoke_stdio.py
uv build

覆盖率门槛为语句和分支均达到 100%。测试通过 MCP 架构和固定版本的 tidalapi 适配器，覆盖每条已注册的读取和变更路由，且不会连接 TIDAL。stdio 冒烟测试会启动打包后的协议进程，并验证全部 122 个工具架构。

正式版本通过 GitHub Actions 使用 npm Trusted Publishing 发布，不使用长期有效的 npm 写入令牌。npm 会自动附加来源证明，同一发布工作流还会通过 GitHub OIDC 将匹配的元数据发布到官方 MCP Registry。

可选的已认证冒烟测试仅执行具有代表性的读取操作：

uv run python scripts/smoke_live_read_only.py

发布维护者可以通过相同的 MCP 客户端路径测试确切的公开 npm 软件包：

uv run python scripts/smoke_live_read_only.py \
  --command npx \
  --server-arg=-y \
  --server-arg=@sickn33/[email protected]

确定性的评估套件和带日期的竞品矩阵让质量声明可供查验。

架构与兼容性

TIDAL 提供开发者 API，但开发者凭据需单独申请，且官方接口未涵盖所有消费者账户工作流。因此，此本地服务固定使用 tidalapi 0.8.11，这是一个围绕 TIDAL 消费者端点构建的非官方适配器，可广泛支持设备登录。TIDAL 的变更可能需要维护；固定版本的依赖和在线冒烟测试会将此风险明确呈现。

该服务通过 stdio 使用 MCP Python SDK。阻塞式上游调用会在异步协议事件循环之外运行。它不会启动 Flask 侧车服务，也不会将身份验证信息存储在临时目录中。

文档

• 完整 API 覆盖范围
• 用例和提示词指南
• 常见问题
• 安全策略
• 竞品证据
• 确定性评估
• 贡献指南
• 变更日志

项目状态

1.4.0 版本新增了将播放列表摘要或比较结果导出为 JSON 的功能，并通过每次调用只解析一次播放列表，降低了每个播放列表工具的网络开销。

许可证、归属和商标声明

MIT。本仓库保留了 yuhuacheng/tidal-mcp 的历史记录和许可证；请参阅 NOTICE.md。

TIDAL 是其各自所有者的商标。本项目是一个独立的非官方社区项目，与 TIDAL 无关，未获得 TIDAL 背书或赞助。项目未附带任何 TIDAL 徽标或专辑封面。