xiaozhi-mcp-music-official

简体中文 | English

---

简体中文

作用

这是一个最小可用的 小智在线音乐 MCP 原型，按小智官方 MCP 接入方式设计。

架构

text 小智 → MCP 接入点 → mcp_pipe.py → music_mcp.py → 在线音乐 API → 本地播放器（mpv） → 返回结果给小智

提供的工具

• - playmusic(query)
• playmusicindex(query, n)
• stopmusic()
• pausemusic()
• resumemusic()
• nexttrack()
• setvolume(level)
• music_info()

当前方案说明

• - 当前接入在线点歌 API
• 支持多源 fallback（优先 kuwo）
• 优先尝试从 API 返回中提取可播放直链
• 用 mpv 直接播放在线 URL
• 如果没有可播放链接，就把歌曲信息返回给小智

启动

bash pip install -r requirements.txt cp .env.example .env python3 mcppipe.py musicmcp.py

环境变量

• - MCPENDPOINT：小智 MCP 接入点
• MUSICAPIKEY：音乐 API key
• MUSICSOURCE：默认优先源，建议 kuwo
• PLAYER_CMD：播放器命令，默认 mpv

注意事项

• - 如果服务器里没有安装 mpv，播放会失败，但搜歌和返回信息仍然可用。
• 当前是最小原型，后续还可以升级成播放列表、上一首/下一首、音量精控、多平台音乐源版本。

---

English

Purpose

This is a minimal working XiaoZhi online music MCP prototype, designed following XiaoZhis official MCP integration style.

Architecture

text XiaoZhi → MCP endpoint → mcp_pipe.py → music_mcp.py → online music API → local player (mpv) → return result to XiaoZhi

Provided tools

• - playmusic(query)
• playmusicindex(query, n)
• stopmusic()
• pausemusic()
• resumemusic()
• nexttrack()
• setvolume(level)
• music_info()

Current approach

• - Uses an online music API
• Supports multi-source fallback (prefers kuwo)
• Tries to extract a playable direct link first
• Uses mpv to play network audio URLs
• If no playable URL is returned, it reports the matched song info back to XiaoZhi

Start

bash pip install -r requirements.txt cp .env.example .env python3 mcppipe.py musicmcp.py

Environment variables

• - MCPENDPOINT: XiaoZhi MCP endpoint
• MUSICAPIKEY: music API key
• MUSICSOURCE: preferred source, recommended kuwo
• PLAYER_CMD: player command, default mpv

Notes

• - If mpv is not installed on the server, playback will fail, but search/info retrieval will still work.
• This is a minimal prototype and can later be extended with playlists, previous/next track, fine-grained volume control, and richer music sources.