kugo-mcp

一个本地 MCP 服务：连接 Windows 酷狗音乐客户端，并通过 Meting-Agent 查询多平台音乐资料。整合了 kugou-native-mcp 和 Meting-Agent。本项目非酷狗官方项目。

功能

资料查询支持 kugou、netease、tencent 和 kuwo。上游还包含客户端搜索、搜索结果播放、收藏播放、设置播放模式和音频链接功能，但这些功能在本机测试中未通过完整验证，因此本服务不对外暴露它们。

播放每日推荐会替换临时播放队列，不修改收藏；服务验证实际播放的歌曲，但无法逐项验证队列。结果受版权、会员、地区和平台接口变化影响。

Related MCP server: gequbao

环境要求

• Windows 10/11，Python 3.11+ 和 Node.js 20+。

• 官方酷狗 Windows 客户端；使用账号相关功能时须登录。

• Python 和 Node 可从终端运行。若 py 没有找到 Python，可用 Python 安装路径替换下文的 py -3。

安装与启动

建议把仓库克隆到持久目录，进入项目目录后执行：

git clone https://github.com/shenruyang123456/kugo-mcp.git
cd kugo-mcp
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .\vendor\kugou-native
npm ci

启动酷狗的本机调试连接。若酷狗已用普通方式启动，请先完全退出，包括系统托盘中的进程：

.\.venv\Scripts\python.exe -m kugou_native_mcp start
.\.venv\Scripts\python.exe -m kugou_native_mcp doctor

在酷狗中打开“推荐”页。默认调试地址为 127.0.0.1:9225，仅供本机使用，不要转发或开放到网络。可用 --port 指定端口，并在 MCP 配置中同步设置 KUGOU_CDP_PORT。

接入 Codex

将下面两个路径替换为实际的项目绝对路径，添加到 Codex 用户目录的 config.toml，然后重启 Codex：

[mcp_servers.kugo-mcp]
command = 'C:\path\to\kugo-mcp\.venv\Scripts\python.exe'
args = ['C:\path\to\kugo-mcp\server.py']
startup_timeout_sec = 30
tool_timeout_sec = 60
default_tools_approval_mode = 'prompt'

[mcp_servers.kugo-mcp.env]
PYTHONIOENCODING = 'utf-8'
KUGOU_CDP_PORT = '9225'
# 如 Node 20+ 不在 PATH，设置 KUGOU_MCP_NODE 为 node.exe 的绝对路径。

可以对 Codex 说：“当前播放什么？”、“显示当前歌曲封面”、“读取我的每日推荐”，或“搜索周杰伦的歌曲”。客户端工具依赖已启动的酷狗；资料查询单独访问各音乐平台。

排查

• 无法连接客户端：确认酷狗已完全退出并通过上述 start 命令启动，在客户端打开“推荐”页，再执行 doctor。启动工具不会自动结束正在播放的客户端。

• 工具无法启动：确认使用 Node 20+，且已运行 npm ci 和 Python 安装命令。如果 Codex 的 PATH 不包含 Node，在配置的环境变量中设置 KUGOU_MCP_NODE。

• 资料为空：平台可能限制资源或要求登录。Meting-Agent 支持 METING_KUGOU_COOKIE 等平台 Cookie 环境变量；不要将 Cookie、账号令牌或私人歌单提交到仓库。

项目在酷狗 20.1.55.27979 上做过有限实测；它依赖非公开的客户端接口，升级后可能需要重新验证。

开发与许可

使用 .\.venv\Scripts\python.exe -m unittest discover -s tests 运行不需要登录酷狗的测试。客户端的端到端功能仍需真实 Windows 客户端验证。

本项目采用 MIT 许可。vendor/kugou-native 保留上游源码及其 MIT 许可；Meting-Agent 作为 npm 依赖安装。平台、客户端和音乐内容归其各自权利人所有。