Skip to main content
Glama

kugo-mcp 1.1

轻量的本地音乐 MCP:连接 Windows 酷狗客户端,读取当前歌曲、封面、同步歌词与进度,控制播放/暂停和上下曲,并通过 Meting-Agent 查询多平台音乐资料。整合 kugou-native-mcp 与 Meting-Agent,非酷狗官方项目。

1.1 的改进

  • 一条持久 CDP 连接,一份歌曲/状态/进度快照,普通查询共用 4.4 秒缓存,没有后台原生轮询。

  • 当前歌曲封面与歌词使用客户端真实 hash,缓存最近 5 首,空结果也缓存;只补缺失项,并发相同请求合并。

  • 歌词解析一次、二分定位当前句;进度本地推算,超过 6 秒停止推算。

  • 播放控制只提交一次,约 600 ms 后读回;重叠操作不排队,超时不自动重复命令。

  • 新启动酷狗后先静置 3 秒,再检查窗口与页面就绪;已有普通客户端或其他程序占用端口时给出原因,不强制结束进程。

  • 上游 MCP 按需启动、空闲 30 秒退出,有请求时不退出。启动与列出工具不连接酷狗、不启动子进程。

  • 旧版 15 个工具名全部保留。每日推荐、收藏和模式只在明确调用时启用,不自动查询。

Related MCP server: CloudMusic Desktop MCP

工具

用途

工具

启动或复用酷狗

kugo_connect(新增)

一次读取歌曲、歌手、封面、歌词和进度

kugo_get_current_track(新增,优先使用)

当前歌曲状态

kugou_get_playback

当前封面

kugo_get_current_cover

当前 LRC、当前句及可选时间轴

kugo_get_current_lyrics(新增)

当前进度和总时长

kugo_get_current_progress(新增)

播放、暂停、上一首、下一首

kugou_control_playback,action 为 play/pause/prev/next

原有账号与模式功能

kugou_get_daily_recommendations、kugou_play_daily_recommendations、kugou_get_favorites、kugou_get_play_mode

多平台音乐资料

platforms、search、song、album、artist、playlist、lyric、pic

共 19 个工具。完整参数、返回值、缓存和错误行为见 API.md,升级变化见 CHANGELOG.md。

安装

Windows 客户端功能需要 Windows 10/11、Python 3.11+、Node.js 20+ 和已安装的官方酷狗。纯 Meting 资料查询不需要启动酷狗。建议安装到持久的用户目录,例如 %USERPROFILE%\.codex\mcp\kugo-mcp,不要放入会清理的临时工作区。

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

保留整个仓库,server.py 会导入同目录的 kugo_mcp 包;不要只复制单个 server.py。Python 依赖随 vendor 安装,Meting 固定为 npm 版本 1.6.11。vendor 的版本号保留上游 0.1.0,聚合服务版本为 1.1.0。

已有安装可先备份配置与本地修改,再更新到 v1.1.0,重新执行 Python 安装和 npm ci,并重启 MCP 客户端。不需要替换 Windows 酷狗或清除账号资料。自定义的 Meting 路径可以继续使用 KUGO_MCP_HOME(支持根目录 node_modules 及 meting/node_modules 两种布局);它只指定依赖位置,不改变源码或服务版本。

连接酷狗

可直接在 MCP 中调用 kugo_connect,或者执行:

.\.venv\Scripts\python.exe server.py start
.\.venv\Scripts\python.exe server.py doctor

doctor 只核对窗口和官方调试页面,不读取歌曲,也不会启动酷狗。start 最多启动一次,不会循环拉起。默认调试地址 127.0.0.1:9225 仅供本机使用,不要转发到外网。可设置 KUGOU_CDP_PORT 改端口;客户端与 MCP 必须一致。可用 KUGOU_EXE_PATH 指定已安装的 KuGou.exe。

若已普通启动酷狗、没有调试页面,请先完全退出(包括托盘),再执行 start。在客户端打开“推荐”页,让官方内嵌页面可用。退出 MCP 会清理自己启动的上游子进程,保持酷狗运行。

接入 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 不在 PATH 时设置 KUGOU_MCP_NODE = 'C:\path\to\node.exe'

可说:“连接酷狗”、“显示当前歌曲、封面和歌词”、“下一首”或“搜索周杰伦的歌曲”。显示连续进度的应用应根据采样时间本地更新,不必每帧查询 MCP;优先一次调用整合信息工具。并行运行多套客户端采样器仍会叠加压力。

限制及排查

  • 本项目使用非公开客户端接口,不能保证所有酷狗版本或长期运行都不挂起。20.1.55.27979 有历史有限实测;新旧接口仍需分别验证。

  • accepted=true 或超时不保证操作结果。verified=false 时不要自动重发,应稍后读取实际状态。next/prev 需要旧 hash 才能比较验证。

  • 兼容的模式读取沿用上游控件方案;不自动调用、不新增设置模式,也不绕过原有版本保护。每日推荐播放会替换临时队列,不能逐项验证队列内容。

  • 进度跳转、原生搜索及收藏播放等旧版未暴露工具仍未启用。桌面组件界面和 EXE 不在这个 MCP 仓库中。

  • 资料结果受版权、会员、地区与接口变化影响;封面或歌词失败会单独报告,其他功能继续可用。Cookie 可由 Meting 环境变量提供,不要提交账号令牌、Cookie 或私人歌单。

  • Meting 空闲退出后,下一次缺失资料会有进程初始化耗时;播放控制与其独立。封面返回 URL,不携带大图片。此仓库没有桌面组件的 HTTP 服务端口,因此不占用 8765。

  • 初始化和 list_tools 成功并不表示酷狗已经连接;先使用 connect 或 start,遇到窗口未响应时等待,避免频繁重试。

开发与发布

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
node tests/test_native_bridge.cjs

测试覆盖持久连接、输入校验、缓存与限频、取消与过期控制、启动等待、5 首 LRU、歌词定位及上游进程生命周期。Windows 实机验证需要真正的客户端;自动测试不依赖登录或改动收藏。

GitHub Actions 在 main 与 PR 上测试 Python 3.11/3.13;main 测试通过后,根据 package.json 版本与 RELEASE_NOTES.md 创建同名版本标签及 Release。已存在的 Release 不覆盖。详细本地验收记录见 VALIDATION.md。

MIT 许可;vendor/kugou-native 保留上游代码和许可,Meting-Agent 作为 npm 依赖。音乐、平台与客户端归各自权利人所有。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    • Generate full songs with vocals, instrumentals and sound effects from text. One server for Suno, Google Lyria, Mureka, MiniMax, ACE-Step, YuE and ElevenLabs. Your agent can quote the credit cost before generating, start a song, wait for it to finish and return download links. Sign in with OAuth; optional daily credit caps; retries never charge twice.

      https://www.raomusic.com/api/mcp
    • Search MusicBrainz artists, releases, works, labels; resolve ISRC/ISWC/barcode; fetch cover art.

    • Spotify MCP server for ChatGPT, Claude and any AI agent: search songs and artists, list playlists, read playlist songs, create playlist, add songs to playlist, remove songs from playlist, set playlist public or private and save to Liked Songs in your own Spotify account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Spotify yourself; Cotlet does not store your password and you need no Spotify API key. About the official Spotify API: Spotify has a full Web API and, since 23 Apr 2026, an official connector for Claude (checked 5 Nov 2026). The API needs an app you register, and in development mode the app owner must have Premium and the app allows 5 users; unlimited users need a registered business with at least 250,000 monthly users. Setup and FAQ: https://cotlet.dev/integrations/spotify-api-mcp-server

      https://cotlet.dev/mcp/v1/spotify
    • ScoreStarling is an all-in-one AI sheet music assistant. Ask for anything to do with sheet music: transcribe a song from audio, video or a link, read a PDF or photo, add chords, change the key, make it easier, turn it into guitar TAB or jianpu, or arrange it for another instrument. Every change lands on a real score you can hear, fix and download (PDF, MIDI, MusicXML, guitar TAB, jianpu, audio). Hosted remote server with OAuth sign-in. Free accounts get monthly credits and free previews; prices are at scorestarling.com/pricing. Setup: https://scorestarling.com/mcp

      https://mcp.scorestarling.com/mcp

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Controls the official NetEase Cloud Music desktop client on Windows, enabling AI to search, play, manage queues, and adjust playback settings via a local control channel.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI clients to control the Windows NetEase Cloud Music desktop app via local stdio MCP, including reading current song and liked state, searching and playing tracks, playback control, track skipping, and setting the current song's liked status.
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control a local NetEase Cloud Music client in natural language — searching songs and playlists, playing or queuing tracks, replacing the queue with a playlist, and pausing, skipping, or adjusting volume — via a BetterNCM plugin and localhost bridge with token authentication.
      8 npm
      MIT