Xiaozhi MCP Music Node

QQMusic MCP（节点助手）

基于节点的辅助模块，反映了人工智能客户端使用的QQ音乐MCP工具。此存储库通过CLI和FastMCP清单公开相同的搜索和播放分辨率原语，同时将所有QQ Music HTTP/签名逻辑保存在共享助手中。

需求

• Node.js 18+（通过以下方式启用CommonJS模式 type: "commonjs" 在 package.json).
• A有效 QQM_COOKIE （请参阅下面的配置部分）。

快速启动

1. 安装依赖项（存储库保留 pnpm-lock.yaml但是 npm install 也有效）：

   pnpm install

1. 复制 .env.example 到 .env 并注入您的QQ音乐cookie字符串：

   cp .env.example .env
   # edit .env and replace the placeholder QQM_COOKIE value

1. 运行CLI以检查可用操作：

   npm run cli -- --help

CLI使用情况

CLI镜像清单工具，并打印标准化的JSON以实现下游自动化。

• 按歌词或歌曲标题搜索：

  npm run cli -- search-lyrics "ready to love" --page 1 --limit 3

• 解析歌曲的播放URL：

  npm run cli -- get-url 0039MnYb0qxYhV

每个命令都验证数字选项（页面/限制）和质量代码(m4a, 128, 320, flac)在调用中定义的共享助手函数之前 qqmusic_mcp.js.

Docker镜像

包括 Dockerfile 安装 pnpm （通过 https://registry.npmmirror.com)并使用 mcp_pipe.js 作为容器入口点，因此清单工厂可以通过管道连接到远程MCP网关。

docker build -t xiaozhi-mcp-music-node .
docker run --rm \
  -e QQM_COOKIE="$QQM_COOKIE" \
  -e MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=..." \
  xiaozhi-mcp-music-node local-stdio-qqmusic

QQM_COOKIE 和 MCP_ENDPOINT 会在 Dockerfile 中作为预设环境变量声明（默认为空），容器启动时仍需通过 -e 或 .env 传入真实值。

将所需的服务器名称作为参数传递（或省略它以从管道传输每个启用的服务器 mcp_config.json).如果需要运行独立CLI，请覆盖入口点：

docker run --rm \
  -e QQM_COOKIE="$QQM_COOKIE" \
  -e MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=..." \
  xiaozhi-mcp-music-node node cli.js -- search-lyrics "ready to love"

FastMCP清单

qqmusic_mcp.js 初始化a FastMCP 使用两个工具的清单(search_music_by_lyrics 和 get_music_url_by_songmid)因此，您可以通过stdio/SSE/HTTP将助手程序插入任何MCP主机。

• 启动stdio清单：

  node qqmusic_mcp.js

• 为宿主平台发送清单文件：

  node qqmusic_mcp.js build-manifest path/to/manifest.json

清单使用 FastMCP的内置 stdio 默认运输；更新您的编排器配置（例如， mcp_config.json 或远程MCP主机）指向 node qqmusic_mcp.js 如果你需要特定的运输线路。

MCP管道助手

mcp_pipe.js 通过流式传输stdio，通过WebSocket/HTTP将正在运行的MCP清单转发到远程MCP集线器 MCP_ENDPOINT （阅读自 .env 如果存在）。它还允许您从以下位置启动任何配置的服务器 mcp_config.json 并将其附加到端点。

1. 设置您的 .env （或导出）带有可访问端点令牌：

   export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=..."

现有 .env.example 已包含此占位符。

1. 运行命名服务器的管道：

   node mcp_pipe.js local-stdio-qqmusic

无需任何争论，脚本每次启用时都会自动执行 mcpServers 入口和管道并行，跳过任何 "disabled": true.

1. 需要代理Python MCP桥或自定义脚本吗？传递本地路径，脚本将直接生成(python 是回退二进制文件，但可以通过以下方式覆盖 MCP_PYTHON).您还可以通过设置将助手指向其他服务器列表 MCP_CONFIG 转到另一个JSON路径。

助手使用 undici 为了控制WebSocket，请确保安装了依赖项(pnpm install/npm install).

配置提示

• QQM_COOKIE （必填）：从浏览器会话中复制（导出或粘贴到 .env). qqmusic_service.js 通过以下方式加载此cookie dotenv 如果它不见了就扔。
• MCP_ENDPOINT （可选 .env.example)：要求 mcp_pipe.js 当您想将任何本地清单转发到远程MCP网关时。在运行管道帮助程序之前，将其设置为WebSocket/HTTP MCP URL加令牌。
• mcp_config.json：为管道助手定义可重用的MCP服务器。包括 local-stdio-qqmusic 入口现在指向 node qqmusic_mcp.js，但您可以添加更多传输（带有自定义标头的SSE/HTTP）或通过切换启用/禁用条目 "disabled".

项目结构

• cli.js：围绕这两个清单工具的CLI包装器。
• qqmusic_mcp.js：FastMCP清单定义、处理程序规范化和清单生成器。运行不带参数的脚本会启动 stdio MCP服务器。
• qqmusic_service.js：构建经过身份验证的QQ音乐服务助手，管理Cookie，并公开助手方法(buildMainClient, buildServiceClient).
• qqmusic_client.js + sign_helper.js：实现每一个QQ音乐HTTP请求和API所需的基于JavaScript的签名逻辑。
• loader.js, main.js, module.js, ventor.js：支持镜像原始QQ音乐网络签名/加载器堆栈的脚本，可用于调试或签名实验。

贡献

欢迎捐款。跑 pnpm install （或 npm install)然后是相关的CLI命令(node qqmusic_mcp.js 或 npm run cli)以验证您的更改。

致谢

多亏了https://github.com/ZWD11/QQmusicApi为QQ音乐API逆向工程提供灵感。

许可证

MIT License | MIT 许可证