抓取歌曲 MCP

个人本地音乐抓取 MCP server。通过 Claude 自然语言完成"搜歌 -> 下载 -> 配歌词 -> 整理本地库"。

架构

三层单向依赖（mcp -> core -> sources）：

• sources：源适配器，统一 Protocol。网易云（自实现 weapi：搜索/下载/歌词）+ LRCLIB（httpx：仅歌词）。下载链路只接网易云一个源；歌词链路双源择优（synced 优于 plain）。
• core：编排层。SearchOrchestrator / DownloadManager / LyricsMatcher / LibraryStore(SQLite)。
• mcp：fastmcp 暴露 5 个 tool。

详见 docs/superpowers/specs/2026-07-21-music-mcp-design.md。

安装

要求 Python ≥ 3.11。

git clone <repo-url> music-mcp && cd music-mcp
pip install -e ".[dev]"      # 装主包 + 依赖（含 cryptography）+ 测试
pytest -q                    # 单测全绿即环境就绪

装完后 music-mcp 命令可用（见 pyproject.toml 的 [project.scripts]）。网易云源自实现 weapi，无需额外依赖或步骤。

网易云源

网易云源自实现 weapi 客户端（双层 AES + 自定义 RSA），依赖 cryptography，已随主包 pip install -e ".[dev]" 安装，无需额外步骤。

• 游客模式：默认无登录态，音质写死 exhigh（约 320k）；无损需登录（本期未实现）。
• 下载只能拿到「游客可听」的歌：版权/VIP/付费曲 get_song_url 返回 url=None，属正常现象。
• 只能「搜索命中」后下载，不能枚举全站曲库；搜不到的曲拿不到。
• 歌词只读 lrc.lyric（带时间轴）+ tlyric.lyric（翻译）；网易云的逐字歌词 yrc 未读，若某曲只有 yrc 则该源返回空，退回 LRCLIB 兜底。
• 可选注入登录态：设 MUSIC_MCP_NETEASE_COOKIE（如 MUSIC_U=...），为未来登录扩展预留。

配置（环境变量）

变量	默认	说明
MUSIC_MCP_DOWNLOAD_DIR	./downloads	歌曲下载目录（download_song 不传 target_dir 时用此值）
MUSIC_MCP_LYRICS_DIR	（空）	歌词存储目录；设置后 get_lyrics 自动写 {artist} - {title}.lrc，无需音频文件存在。留空则歌词只写在与音频同目录（需音频已存在）
MUSIC_MCP_DB_PATH	./library.db	SQLite 索引路径
MUSIC_MCP_NETEASE_MIN_INTERVAL_MS	800	网易云请求最小间隔（ms）
MUSIC_MCP_NETEASE_COOKIE	（空）	网易云登录 cookie（可选，如 MUSIC_U=...）
MUSIC_MCP_NETEASE_TIMEOUT	10.0	网易云请求超时（秒）
MUSIC_MCP_LOG_LEVEL	INFO	日志级别

歌曲与歌词存储路径即通过以上两个变量配置：MUSIC_MCP_DOWNLOAD_DIR 决定歌曲落盘位置，MUSIC_MCP_LYRICS_DIR 决定歌词落盘位置。两者均为可选，留空时歌曲默认 ./downloads、歌词不单独落盘（仅在与音频同目录时写）。

接入 Claude

配置时把歌曲/歌词存储路径用环境变量设好，之后所有 tool 自动用这两个目录，无需每次传参。

Claude Desktop

编辑配置文件（Windows: %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "music-mcp": {
      "command": "music-mcp",
      "env": {
        "MUSIC_MCP_DOWNLOAD_DIR": "D:/music/downloads",
        "MUSIC_MCP_LYRICS_DIR": "D:/music/lyrics",
        "MUSIC_MCP_DB_PATH": "D:/music/library.db"
      }
    }
  }
}

Claude Code

命令行注册（无需手编 JSON）：

claude mcp add music-mcp \
  -e MUSIC_MCP_DOWNLOAD_DIR=D:/music/downloads \
  -e MUSIC_MCP_LYRICS_DIR=D:/music/lyrics \
  -e MUSIC_MCP_DB_PATH=D:/music/library.db \
  -- music-mcp

若 Claude 报找不到 music-mcp 命令，把 command 换成 python -m music_mcp.server，或指向 venv 里该命令的绝对路径。

使用

接入后直接用自然语言驱动，5 个 tool 都支持「norm_key（来自搜索结果）」或「title + artist」两种入参形态。

帮我搜周杰伦的晴天                  # search_songs
下载这首歌                          # download_song（用上一步的 norm_key）
下载 晴天 周杰伦                    # download_song（直接 title+artist）
给我这首歌的歌词                    # get_lyrics
扫描 D:/music 这个目录并补歌词      # scan_library
本地库里有哪些没歌词的              # query_library

典型流程：搜歌 → 下载 → 配歌词 → 扫描整理本地库 → 查询库。下载默认落 MUSIC_MCP_DOWNLOAD_DIR，歌词默认落 MUSIC_MCP_LYRICS_DIR（设了的话）。

提供的 tool

Tool	说明
search_songs	按关键词搜索歌曲，标记是否已入库
download_song	下载歌曲到本地（幂等，传 norm_key 或 title+artist）；target_dir 省略时用 MUSIC_MCP_DOWNLOAD_DIR
get_lyrics	获取歌词（LRC 优先）；audio_dir 提供时写同名 .lrc，否则写 MUSIC_MCP_LYRICS_DIR（设了的话）
scan_library	扫描本地音频目录，补元数据并触发歌词补全
query_library	查询本地库，可按关键词/有无歌词过滤

测试

pytest -q          # 单元测试（不发真网络请求）

代码探索（可选，开发者）

仓库可用 codegraph 查调用链与影响面。未装可 npm i -g @colbymchenry/codegraph；索引数据 .codegraph/ 已 git 忽略（本地产物，clone 后需重建）：

codegraph init           # clone 后首次建索引
codegraph sync           # 改代码后增量同步
codegraph status         # 查看索引是否最新
codegraph impact <符号>   # 改某符号前看影响面

手动 smoke test

python scripts/smoke_test.py "晴天" "周杰伦"

真实连网易云 + LRCLIB 跑搜索/下载/歌词全流程。不进自动化测试。

能力边界

以下是当前实现的真实边界，避免对能力过度预期。

下载

• 只能下载网易云「游客可听」的曲；版权/VIP 曲 url=None 会失败。
• 音质写死 exhigh；无损需登录态（未实现）。
• 只接网易云一个下载源（LRCLIB 不提供音频），该源限流/不可用时无备胎。

歌词

• 双源择优：网易云（带时间轴 LRC 优先）-> LRCLIB 兜底；多数热门曲能拿到带时间轴 LRC。
• 不制作时间轴：只转发源里现成的 LRC。若两源都只有纯文本，落盘即纯文本歌词，系统不做音频对齐/强制时间戳。
• 网易云逐字歌词 yrc 未读，仅读 lrc（时间轴）+ tlyric（翻译）。
• 纯器乐 / 极冷门 / 刚发行的曲可能两边都无歌词，返回查不到。

风险说明

• 网易云抓取违反其 ToS，账号有被封风险，仅供个人学习与本地使用。
• 反爬细节集中在 netease/ 包内（weapi.py 加密 + client.py 请求），核心业务层不碰加密参数；接口变更时改动集中可见。
• 不分发版权音乐。