netease-music-mcp

netease-music-mcp 是面向通用 MCP Client 的网易云音乐数据服务器。它以紧凑、分页、 结构化的方式提供歌曲、歌手、专辑、歌单、歌词和登录用户音乐库数据，可供 Claude Desktop、 Codex、IDE Agent、Yuki 等 MCP Client 使用。

当前开发版本：1.0.0。本项目是独立的社区项目，不是网易云音乐官方项目，也未获得网易公司的 认可或担保。所用 Web 接口不是公开稳定 API，可能随上游变更。

项目不调用任何 LLM，不下载、播放或转发音频，不提供付费音频链接，也不绕过会员、版权、 地区或 DRM 限制。写操作默认关闭；仅当显式设置 NETEASE_WRITE_OPERATIONS_ENABLED=true 后才会 启用，且每次写调用仍必须传入 confirm=true。项目不提供删除歌单接口。

安装

本地开发需要 Python 3.12 与 uv：

git clone <repository-url> netease-music-mcp
cd netease-music-mcp
uv sync --all-extras

公开查询无需 Cookie。访问私人音乐库前，将 .env.example 复制为 .env 并配置 NETEASE_COOKIE 与 NETEASE_USER_ID。服务不会自动读取浏览器 Cookie。

Windows 与 macOS 部署建议直接使用 Docker Desktop；仅用 .env 启动容器时宿主机不需要 Python， 网易云 Cookie 通过项目目录的 .env 注入容器。Docker Compose 使用具名缓存卷，不依赖宿主机路径格式。 如果使用下方 auth 宿主机导入命令，则宿主机需要 Python 3.12 与 uv；Keychain/DPAPI 不能在 Linux 容器内部代替宿主机读取。

启动

stdio：

uv run netease-music-mcp serve --transport stdio

Streamable HTTP（默认路径 /mcp）：

uv run netease-music-mcp serve \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8766

辅助命令：

uv run netease-music-mcp config
uv run netease-music-mcp doctor
uv run netease-music-mcp cache stats
uv run netease-music-mcp cache clear

config 仅显示非敏感值、配置来源和 Cookie 是否已配置，不会显示 Cookie 内容。 doctor 检查配置、缓存可写性、公开查询和（已配置时）登录状态。

宿主机本地认证导入

Windows/macOS 桌面客户端登录态可由宿主机在运行前读取。导入器只读取网易云桌面客户端的 本地 MMKV Cookie 归档，并兼容 CEF Chromium Cookie 数据库；首次运行必须确认。读取加密的 CEF Cookie 时，macOS 使用 Keychain，Windows 使用 DPAPI。它不会扫描浏览器，不会打印 Cookie， 也不会把 Cookie 写入仓库或镜像。

仅查看脱敏结果：

uv run netease-music-mcp auth import-local

确认后直接以一次性环境变量启动 Docker（默认重新构建镜像）：

uv run netease-music-mcp auth run-docker --detach

run-docker 只把 Cookie 传给本次 docker compose 子进程；接口请求使用固定的 appver=2.9.7， 导入器不落盘。 使用 --detach 时，Cookie 会随运行中的本地容器存在；停止后执行 docker compose down 清理。 非交互环境必须显式使用 --yes，否则导入会拒绝执行。客户端未登录、存储不存在或系统密钥 访问失败时会返回明确错误，不会使用空 Cookie 继续启动。

十五个工具

搜索结果只保留概要；歌曲详情使用批量工具读取。专辑和歌单默认不包含曲目，歌词默认只返回 一页。MCP 响应使用 structuredContent，兼容文本内容仅为一句短摘要。

完整参数见 docs/tools.md，模型见 docs/data-models.md。

四类资源

资源以 application/json 返回，并复用工具的验证、缓存和错误处理路径。需要曲目列表或热门 歌曲时，继续使用相应工具的显式分页/数量参数。

认证与数据边界

无需登录：搜索、歌曲、歌手、专辑、公开歌单、歌词、推荐、新歌速递和排行榜（以上游允许为准）。

需要 Cookie：用户歌单、收藏歌手、收藏专辑、每日推荐、播放记录和喜欢的歌曲。user_id 未传时使用 NETEASE_USER_ID；无登录态会返回 authentication_required，不会返回空列表伪装成功。

可直接配置完整 NETEASE_COOKIE，或使用 NETEASE_MUSIC_U 与 NETEASE_CSRF 由认证组件 统一组装。Cookie 不进入日志、异常、MCP 输出或缓存。详见 docs/authentication.md。

写工具仅对已认证账号开放。真实测试建议先读取歌单和喜欢状态，选择原本未存在的歌曲执行 “添加后删除”或“点赞后取消点赞”，并在每一步核对恢复结果。

Yuki 接入

stdio .mcp.json 示例：

{
  "mcpServers": {
    "netease_music": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/netease-music-mcp",
        "run",
        "netease-music-mcp",
        "serve",
        "--transport",
        "stdio"
      ],
      "env": { "NETEASE_COOKIE": "${NETEASE_COOKIE}" },
      "lifecycle": "lazy",
      "yuki": {
        "scope": "mcp.netease_music",
        "summary": "歌曲、歌手、专辑、歌单、歌词和音乐库查询",
        "tags": ["音乐", "网易云", "歌曲", "歌手", "专辑", "歌单", "歌词"]
      }
    }
  }
}

HTTP 示例：

{
  "mcpServers": {
    "netease_music": {
      "url": "http://127.0.0.1:8766/mcp",
      "lifecycle": "lazy",
      "yuki": {
        "scope": "mcp.netease_music",
        "summary": "网易云音乐数据查询"
      }
    }
  }
}

yuki 仅是 Client 读取的文档字段，本项目不依赖 Yuki。

Docker

docker build -t netease-music-mcp:1.0.0 .
docker compose up --build

Windows PowerShell 使用同样的 Docker 命令；Cookie 可用以下命令准备：

Copy-Item .env.example .env
docker compose up --build

macOS、Windows 和 Linux 的 Compose 行为保持一致：从本地 .env 读取配置，将 SQLite 缓存放入 具名卷，并暴露可配置端口。容器以非 root 用户运行，健康检查只检查 TCP 监听，不调用真实搜索接口。

故障排查

• 启动即配置错误：运行 uv run netease-music-mcp config，检查分页默认值是否超过最大值、 路径是否以 / 开头、端口是否有效。

• 私人数据返回 authentication_required：配置 Cookie 和 NETEASE_USER_ID，再运行 doctor。Cookie 过期会返回 authentication_expired。

• rate_limited：等待后重试；服务器只按配置进行有限指数退避。

• upstream_unavailable：检查网络与网易云状态。

• upstream_response_error：通常表示非公开 Web 接口的响应结构已变，需要更新 Backend 或 Normalizer。

• HTTP Client 无法连接：确认 URL 为 http://host:port/mcp，且容器/防火墙端口一致。

数据与版权

服务器读取并规范化元数据和歌词，也可按显式确认执行歌单和点赞写操作。数据、封面与歌词的权利属于各自权利人；使用者应遵守 网易云音乐服务条款、适用法律及地区限制。本项目不缓存认证响应、Header 或原始上游 JSON。

更多信息：

• 架构

• 配置

• 传输

• Token 效率

• 路线图

• 0.1.0 完成报告