QQ Music MCP

一个在本机运行的 QQ 音乐个人音乐库 MCP Server。它不是"点唱机"，而是你的音乐库管理员：与市面上清一色"搜索 + 播放链接"的 QQ 音乐 MCP 不同，本项目是目前同类中首个支持账号级写入的 QQ 音乐 MCP：AI 可以读取、分析并直接管理你的歌单——创建歌单、批量加歌、移歌、按规则生成歌单，以及完整地整理"我的喜欢"。

仅支持 Windows 10/11。QQ 音乐没有提供这套功能的官方开放 API，本项目使用网站当前的非官方接口，可能随上游改版而失效。

为什么与众不同

1. 账号级写入：真正"管"你的音乐库 ⭐

市面上的 QQ 音乐 MCP 几乎全部只做一件事：搜索歌曲、返回播放链接，只读。本项目直接封装了 QQ 音乐账号接口的完整写能力（musicu.fcg 的 PlaylistBaseWrite / PlaylistDetailWrite）：

• 创建 / 删除歌单

• 批量加歌 / 移歌（每批最多 20 首，写后回读验证）

• 合并、拆分、复制歌单，按规则生成"智能歌单"

这意味着 AI 能替你完成以前只能手动做的事情——把"我喜欢"按语言、流派、场景整理进新歌单，而不是只告诉你"你最好建个歌单"。

2. 写前探针：对不稳定接口的工程级防御

QQ 音乐没有官方 API，写接口随时可能被改版或风控。所以在任何真实写入之前，qqmusic_probe_write 会用一个临时歌单完整验证一遍：

创建 → 加歌 → 回读 → 移除 → 删除

只有全部成功才解锁写入能力（结果缓存到 capabilities.json）；任何一步失败都会自动禁用所有写工具。探针不过，绝不写入。

3. 计划冻结 + 精确回滚：AI 整理不翻车

整理工作流把"AI 干活"变成可审计、可撤销的事务：

• 计划在预览确认后冻结，生成不可篡改的 SHA-256，每次读取都校验完整性

• 每次应用生成 run_id，记录每个歌单、每批添加的歌曲

• 不满意可随时按 run_id 回滚，只撤销本次运行添加的内容

4. 可持续整理：规则同步 + 只处理新增喜欢

规则歌单不再是创建一次就结束：先预览目标歌单与规则结果的差异，再用预览哈希确认写入。后续重复运行时只补充新增歌曲；可选清理不再符合规则的歌曲。增量整理则比较两次"我喜欢"快照，只把新增加的歌曲交给 AI 分类，不必反复分析整个音乐库。

5. 音乐库体检：分析能力是同类空白

重复歌曲、同歌名不同版本、空歌单、歌单交集、未整理歌曲——一套完整的数据分析工具，让你（和 AI）先看清整个音乐库，再决定怎么整理。

6. 数据主权：本地备份 + 完整审计

所有导出、计划、运行记录与每次写操作日志都保存在本机，不经过任何第三方服务器：完整备份"我喜欢"（JSON / CSV / 摘要）、每次加歌 / 移歌 / 删歌的审计日志、每次整理运行的可回滚记录。你的音乐数据始终在你手里。

与常见 QQ 音乐 MCP 的对比

同样接入 QQ 音乐，两类 MCP 干的是两件不同的事：搜索播放类负责"找到歌、放出来"，本项目负责"管好你的音乐库"。

播放链接与下载是搜索播放类 MCP 的主场，本项目刻意不做：它既不是管理歌单的必要环节，也是版权、风控和接口变动最不稳定的部分。把播放交给专业的播放器，把管理做到极致。

一句话：别的 MCP 帮你"找到歌"，这个 MCP 帮你"管好歌"。两者可以同时接入，各司其职。

和其他音乐 MCP 配合使用

本项目与搜索播放类音乐 MCP 是互补关系：让播放类 MCP（或 QQ 音乐客户端）负责找歌、试听，让本项目负责整理、归档、体检。例如先用其他 MCP 搜索试听确认喜欢的歌，再用 qqmusic_add_songs 把它们批量收进对应歌单。

你能让 AI 做什么

• 列出和读取全部自建歌单，也可以只读读取"我喜欢"。

• 创建歌单、批量加歌、移歌和删除空歌单（账号级写入，写前探针 + 回读验证）。

• 完整导出"我喜欢"为 JSON、CSV 和摘要备份。

• 分析整个音乐库：重复歌曲、同歌名不同版本、空歌单、歌单交集、未整理的"我喜欢"。

• 按歌手、专辑、关键词和时长筛选歌曲，创建规则歌单。

• 保存并重复同步规则歌单，写入前展示新增 / 移除差异和确认哈希。

• 比较两次"我喜欢"快照，只整理后来新增的歌曲。

• 分页批量补全发行时间、语言、版本和 Live / Remix / 伴奏标签，结果本地缓存。

• 合并歌单、拆分歌单、复制歌单，同时保留原始歌单。

• 搜索歌曲、读取歌曲详情和歌词。

• 让 AI 按语言、流派、年代、场景或歌手整理/分类/新建歌单。

• 一首歌可进入最多 3 张歌单；写入前先预览，冻结计划后才写回。

• 自动创建或精确复用唯一同名歌单，分批写入并逐批回读验证。

• 记录每次运行和通用操作，支持整理计划的有限回滚。

34 个 MCP 工具

通用歌单操作（账号级写入）

音乐库分析

智能歌单

搜索与音乐信息

整理"我喜欢"工作流

推荐使用流程

整理"我喜欢"时，建议让 AI 严格按下面的顺序执行：

1. 调用 qqmusic_status，确认登录状态和本地能力可用。

2. 调用 qqmusic_export_liked，完整备份"我喜欢"，取得 export_id。

3. 调用 qqmusic_get_export_summary 查看整体信息，再用 qqmusic_get_export_page 分页读取歌曲，避免一次载入过多内容。

4. 调用 qqmusic_create_plan 创建草稿，并用 qqmusic_set_taxonomy 定义分类。系统会自动保留"待整理"分类。

5. AI 分析歌曲后，分批调用 qqmusic_upsert_assignments 写入分类、置信度和理由；每首歌最多进入 3 个分类。

6. 调用 qqmusic_preview_plan 检查覆盖率、各歌单数量和待整理歌曲。此时不会修改 QQ 音乐。

7. 需要调整时继续修改草稿；确认无误后调用 qqmusic_finalize_plan 冻结方案并生成 SHA-256。冻结后不能直接修改，可用 qqmusic_revise_plan 创建新修订。

8. 调用 qqmusic_probe_write，用临时歌单验证当前 QQ 音乐接口是否支持创建、加歌、回读、移除和删除。

9. 只有预览已确认、方案已冻结且探针成功后，才调用 qqmusic_apply_plan 创建或复用目标歌单并分批加歌。

10. 如果本次整理结果需要撤销，使用应用结果中的 run_id 调用 qqmusic_rollback_run。它只撤销该次运行记录的新增歌曲，不会改动"我喜欢"。

可以直接对 AI 这样说：

请按推荐流程整理我的"我喜欢"。先检查状态并完整备份，然后分页读取歌曲，
按语言、流派和使用场景建立分类；低置信度歌曲放入"待整理"。
完成后只给我预览，不要写入。等我明确确认后，再冻结方案、运行写入探针并应用。
任何时候都不要从"我喜欢"删除歌曲。

使用场景

1. 先做一次音乐库体检

请分析我的 QQ 音乐音乐库，不要修改任何内容。
告诉我有多少空歌单、重复歌曲、歌单之间的交集，
以及"我喜欢"里还没有进入任何其他歌单的歌曲。

AI 会调用 qqmusic_analyze_library，必要时继续调用 qqmusic_find_duplicates、qqmusic_find_empty_playlists、 qqmusic_find_unorganized_songs 和 qqmusic_compare_playlists。

2. 合并歌单但保留原歌单

把"通勤"和"开车"合并成一张"驾驶精选"。
重复歌曲只保留一份，原来的两张歌单不要修改。

AI 会读取两张源歌单，调用 qqmusic_merge_playlists。新歌单写入后会回读确认，源歌单不会被删除。

3. 把一张大歌单拆成多个场景

读取我的"收藏精选"，按歌曲气质拆成"通勤""运动""夜晚"三张歌单。
先展示每张歌单包含哪些歌，确认后再创建；原歌单保留。

AI 会先调用 qqmusic_get_playlist，根据歌曲元数据生成分组预览，再调用 qqmusic_split_playlist。

4. 用规则持续创建歌单

从"我喜欢"里找出周杰伦的歌，创建一张"周杰伦精选"，最多 100 首，
不要重复，也不要动"我喜欢"。

AI 会使用 qqmusic_create_smart_playlist，规则可以组合歌手、专辑、关键词和时长：

{
  "keyword": "",
  "singer": "周杰伦",
  "album": "",
  "min_duration_seconds": null,
  "max_duration_seconds": null,
  "limit": 100,
  "deduplicate": true
}

source_directory_id=201 表示从"我喜欢"读取；它只作为来源，不会成为写入目标。

5. 搜索歌曲、查详情和歌词

搜索"晴天"，告诉我有哪些版本；再读取最匹配版本的歌曲详情和歌词。

AI 会调用 qqmusic_search，再根据返回的 MID 调用 qqmusic_get_song_detail 和 qqmusic_get_lyrics。

6. 整理"我喜欢"

请整理我的 QQ 音乐"我喜欢"：先备份，按语言、流派和使用场景分类，
低置信度的歌放入"待整理"。先给我预览和分类理由，确认后再写入。
绝不从"我喜欢"删除歌曲。

这是完整的计划工作流，工具顺序见上方"推荐使用流程"。

7. 让规则歌单跟着"我喜欢"更新

同步"周杰伦精选"：来源是"我喜欢"，保留歌手包含"周杰伦"的歌曲。
先展示新增和移除差异，不要直接写入；这次不要移除我手动放进去的歌曲。

AI 会调用 qqmusic_preview_smart_playlist_sync 保存规则并返回 preview_sha256。你确认后再调用 qqmusic_apply_smart_playlist_sync。 以后使用同一名称和规则再次预览，只会显示新的差异。默认 remove_extraneous=false，因此不会删除用户手动加入的歌曲。

8. 只整理最近新增的喜欢

比较上次快照，只整理后来新加入"我喜欢"的歌曲。
补全这些歌的发行年份、语言和版本信息，然后沿用之前的分类方式。

qqmusic_prepare_incremental_organization 会先保存当前完整快照，再生成只包含新增歌曲的 incremental_export_id。后续直接用这个导出创建整理计划即可。第一次运行且没有历史快照时， 只建立基线，不会把整个音乐库误当成新增内容。检测到从"我喜欢"消失的歌曲时只报告，不执行删除。

9. 批量补全分类所需元数据

读取这个导出的第一页，为歌曲补全发行时间、语言、版本、Live/Remix/伴奏标签，
需要时附带一小段歌词，再根据这些信息分类。

qqmusic_enrich_export_page 每页最多处理 50 首，并发请求数限制为 5。结果缓存在本机 30 天； 默认不读取歌词，启用时也只返回去除时间标签后的前 1200 个字符，避免把大段歌词塞进模型上下文。

MCP 工具提示

所有工具都声明了 MCP annotations。客户端可以区分只读工具、本地状态变更、远端追加和可能移除歌曲的操作， 从而优先选择高层工作流，并在真正的破坏性写入前展示更明确的确认提示。原有底层工具继续保留，兼容已有配置和提示词。

环境要求

• Windows 10 或 Windows 11

• 已安装 Chrome 或 Edge

• 支持 MCP 的 AI 客户端

自动安装脚本会准备 uv 和隔离的 Python 环境，不要求预先安装 Python 或 Node.js。

安装

推荐在 PowerShell 中运行自动安装脚本：

irm https://github.com/baoozak/qqmusic-mcp/releases/latest/download/install.ps1 | iex

脚本会自动：

1. 检查并安装 uv。

2. 下载最新 GitHub Release 的 wheel，并用随 Release 发布的 SHA-256 校验。

3. 安装 qqmusic-mcp，将命令目录加入当前用户的 PATH。

4. 让你选择 Codex、Claude Desktop、Cursor 或 VS Code。

5. 打开 QQ 音乐登录窗口，将登录态用 Windows DPAPI 加密保存。

6. 自动注册 Codex；Claude Desktop、Cursor 和 VS Code 会输出待合并的标准配置。

7. 运行安装检查。

脚本不读取或输出 Cookie。希望先审阅脚本时，可以下载后再运行：

$installer = "$env:TEMP\qqmusic-mcp-install.ps1"
irm https://github.com/baoozak/qqmusic-mcp/releases/latest/download/install.ps1 -OutFile $installer
notepad $installer
powershell -ExecutionPolicy Bypass -File $installer

手动安装

已经安装 uv 时，也可以直接从 GitHub 安装，然后运行一次设置向导：

uv tool install "git+https://github.com/baoozak/qqmusic-mcp.git"
qqmusic-mcp setup --client codex

升级时重新运行安装脚本；卸载使用：

uv tool uninstall qqmusic-mcp

接入 MCP 客户端

推荐使用标准 stdio 传输。客户端负责启动和关闭 MCP，不需要端口、后台服务或 Bearer Token。

Codex

登录、自动注册并检查：

qqmusic-mcp setup --client codex
codex mcp get qqmusic-mcp

等价的手动命令：

codex mcp add qqmusic-mcp -- qqmusic-mcp stdio

Claude Desktop

先登录并生成配置：

qqmusic-mcp setup --client claude

将输出中的 mcpServers 合并到 Claude Desktop 配置文件。典型配置如下：

{
  "mcpServers": {
    "qqmusic-mcp": {
      "command": "qqmusic-mcp",
      "args": ["stdio"]
    }
  }
}

Cursor

qqmusic-mcp setup --client cursor

将输出合并到项目 .cursor/mcp.json 或 Cursor 的全局 MCP 配置。

VS Code

qqmusic-mcp setup --client vscode

将输出保存或合并到 .vscode/mcp.json：

{
  "servers": {
    "qqmusic-mcp": {
      "type": "stdio",
      "command": "qqmusic-mcp",
      "args": ["stdio"]
    }
  }
}

如果客户端找不到 qqmusic-mcp，运行 Get-Command qqmusic-mcp，然后把配置中的 command 换成输出的完整路径。

首次登录

自动安装脚本和 qqmusic-mcp setup 会在注册 MCP 客户端之前打开隔离的 Chrome 窗口；Chrome 不可用时尝试 Edge。使用 QQ 或微信登录 QQ 音乐即可，检测到登录态并完成服务端验证后窗口自动关闭。这样登录不会占用 MCP 的启动握手时间。

登录 Cookie 不会以明文写入磁盘、日志或 MCP 响应。它通过 Windows DPAPI 加密保存到：

%LOCALAPPDATA%\QQMusicOrganizer\session.dpapi

该文件只能由当前 Windows 用户解密。后续启动会自动复用；只有 QQ 音乐明确返回登录失效时才重新打开登录窗口。主动退出：

qqmusic-mcp logout

需要重新登录或单独检查安装时：

qqmusic-mcp login --force
qqmusic-mcp doctor --client codex

HTTP 模式

只有确实需要固定本地 URL 时才使用 Streamable HTTP。服务只绑定 127.0.0.1，并强制要求至少 32 字符的 Bearer Token。

$token = qqmusic-mcp token
[Environment]::SetEnvironmentVariable("QQMUSIC_ORGANIZER_TOKEN", $token, "User")
$env:QQMUSIC_ORGANIZER_TOKEN = $token
qqmusic-mcp start
qqmusic-mcp status

MCP URL：http://127.0.0.1:8765/mcp

停止服务：

qqmusic-mcp stop

直接前台运行也可以：

qqmusic-mcp serve --port 8765 --login-timeout 600

CLI

qqmusic-mcp stdio                     标准 MCP stdio 服务
qqmusic-mcp serve                     前台 HTTP 服务
qqmusic-mcp start/status/stop         管理后台 HTTP 服务
qqmusic-mcp login [--force]           登录并用 DPAPI 保存会话
qqmusic-mcp setup --client <client>   登录、注册并检查安装
qqmusic-mcp doctor --client <client>  检查命令、浏览器、登录和注册
qqmusic-mcp install --client codex    注册 Codex MCP
qqmusic-mcp config --client <client>  输出客户端配置
qqmusic-mcp logout                    删除 DPAPI 登录缓存
qqmusic-mcp uninstall [--purge]       移除 Codex 注册，可选退出登录
qqmusic-mcp token                     生成 HTTP Bearer Token

数据与安全

本地数据位于 %LOCALAPPDATA%\QQMusicOrganizer：

• exports/：歌曲快照、CSV 和摘要。

• plans/：草稿、冻结计划、预览和 SHA-256。

• runs/：写入及回滚日志。

• operations/：通用歌单操作日志，可用于审计和人工回溯。

• smart_playlists/：规则歌单定义、最近一次差异预览与确认哈希。

• metadata/：按歌曲 MID 缓存的详情、分类辅助字段和可选歌词片段。

• capabilities.json：最近一次写入探针结果。

• session.dpapi：DPAPI 加密后的登录态。

安全边界：

• 标准模式使用 stdio，不开放网络端口。

• HTTP 模式仅监听 localhost 并校验 Bearer Token。

• 写回前必须完成创建、加歌、读取、移除和删除探针。

• 每批最多写入 20 首，并在写后回读确认。

• 同名歌单不唯一时停止，避免写错目标。

• "我喜欢"永远不是写入、删除或回滚目标。

• 通用工具的每次写操作都会记录日志；需要撤销时优先使用整理计划工作流的回滚能力。

• Cookie、令牌和完整认证错误不进入日志。

详见 SECURITY.md。

限制

• 本项目不是腾讯或 QQ 音乐官方产品，也与其无关联。

• QQ 音乐网站接口、登录流程或风控变化可能导致功能失效。

• 不提供播放链接与下载：这是刻意的定位选择（见"与常见 QQ 音乐 MCP 的对比"）；试听请使用搜索播放类 MCP 或 QQ 音乐客户端。

• MCP 提供数据和安全写入工具，不内置大模型；分类质量取决于使用它的 AI 客户端。

• 部分下架、地区限制或异常歌曲可能进入"待整理"。

• 歌词和歌曲详情是否可用取决于 QQ 音乐当前的版权和接口返回。

• 回滚不会恢复 QQ 音乐服务端自身的历史状态，只处理本项目运行日志记录的新增内容。

故障排查

查看 MCP 是否安装：

Get-Command qqmusic-mcp
qqmusic-mcp --help

登录窗口被关闭或登录已失效：

qqmusic-mcp login --force --login-timeout 600
qqmusic-mcp doctor --client codex

命令在当前窗口找不到：安装器已更新当前用户的 PATH，请重新打开 PowerShell 后再运行 qqmusic-mcp doctor。

HTTP 服务未就绪：

qqmusic-mcp status
Get-Content "$env:LOCALAPPDATA\QQMusicOrganizer\service.err.log" -Tail 50

写入失败：不要绕过探针。保留本地计划和运行日志，更新到最新版后重新执行 qqmusic_probe_write。

许可证

MIT