ytmusic-mcp

一个 MCP 服务器，封装了 ytmusicapi，使 Claude（或任何 MCP 客户端）能够搜索 YouTube Music、管理你的播放列表以及读取你的收听历史。

工具

未包含（v1）： 基于 BPM 的推荐。YouTube Music 不暴露节奏数据，因此需要第二个数据源（例如音频分析 API）——这是未来版本的一个延伸目标，不属于本次构建的一部分。

Related MCP server: mcp-server-youtube

设置

1. 安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. 身份验证

没有官方的 YouTube Music API，因此 ytmusicapi 通过重用你已登录浏览器会话中的标头来进行身份验证。

1. 在 Firefox（推荐——其原始标头复制比 Chrome 更可靠）中打开 music.youtube.com 并登录。

2. 打开开发者工具（Cmd+Option+I / F12）→ 网络 标签页 → 按 browse 过滤。

3. 点击进入一个播放列表，或重新加载页面，以触发一个 browse POST 请求。

4. 点击该请求 → 标头 标签页 → 切换 原始标头 → 选择并复制整个块。

5. 将其粘贴到项目根目录下名为 raw_headers.txt 的新文件中并保存。

6. 运行：

   python scripts/setup_auth_from_file.py

   这将写入 headers_auth.json 并删除 raw_headers.txt。

或者，python scripts/setup_auth.py 通过交互式终端提示（而不是文件）执行相同操作，如果你更愿意直接粘贴的话。

headers_auth.json 等同于你的已登录会话——切勿提交或共享它。 它已被添加到 gitignore。

在继续之前验证身份验证是否有效：

python scripts/test_search.py

这些标头会定期过期/轮换。如果工具开始因身份验证错误而失败，请重新执行此步骤。

3. 添加到 Claude Code

claude mcp add ytmusic -s user \
  -e YTMUSIC_AUTH_PATH="$(pwd)/headers_auth.json" \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

-s user 使其在任何 Claude Code 会话中可用，而不仅限于此目录。对 Python 解释器、server.py 和 YTMUSIC_AUTH_PATH 使用绝对路径，因为服务器可以从任何工作目录启动。

对于其他 MCP 客户端（Claude Desktop 等），使用它们各自的配置格式将其指向相同的命令和环境变量。

错误处理

工具调用将常见的失败模式转换为清晰的消息，而不是原始回溯：

• 缺失/过期/格式错误的身份验证 → 提示你重新运行 scripts/setup_auth_from_file.py。

• 速率限制（HTTP 429） → 提示你等待并重试。

• 受限/受限制的内容 → 报告为不可用，而不是崩溃。

• 网络错误 → 直接报告。

许可证

MIT — 参见 LICENSE。