kugo-mcp
一个本地 MCP 服务：连接 Windows 酷狗音乐客户端，并通过 Meting-Agent 查询多平台音乐资料。整合了 kugou-native-mcp 和 Meting-Agent。本项目非酷狗官方项目。
功能
| 类别 | MCP 工具 | 用途 |
|---|---|---|
| 客户端 | kugou_get_playback |
读取当前歌曲和播放状态 |
| 客户端 | kugou_get_daily_recommendations |
读取账号的每日推荐 |
| 客户端 | kugou_play_daily_recommendations |
从指定曲序播放每日推荐 |
| 客户端 | kugou_get_favorites |
分页读取收藏歌单 |
| 客户端 | kugou_control_playback |
播放或暂停 |
| 客户端 | kugou_get_play_mode |
读取当前播放模式 |
| 资料 | platforms、search |
列出平台、按关键词搜索 |
| 资料 | song、album、artist、playlist |
查询歌曲、专辑、歌手和歌单 |
| 资料 | lyric、pic |
查询歌词和封面链接 |
| 组合 | kugo_get_current_cover |
根据当前酷狗歌曲获取封面 |
资料查询支持 kugou、netease、tencent 和 kuwo。上游还包含客户端搜索、搜索结果播放、收藏播放、设置播放模式和音频链接功能，但这些功能在本机测试中未通过完整验证，因此本服务不对外暴露它们。
播放每日推荐会替换临时播放队列，不修改收藏；服务验证实际播放的歌曲，但无法逐项验证队列。结果受版权、会员、地区和平台接口变化影响。
环境要求
- 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 依赖安装。平台、客户端和音乐内容归其各自权利人所有。