Xiaozhi Mcp Music Official

按小智官方 MCP 接入方式，为小智增加在线音乐播放能力。适用于已经有小智 MCP 接入点（wss://api.xiaozhi.me/mcp/?token=...）并希望通过 MCP 工具实现搜歌、播放、暂停、继续、停止等在线音乐控制的场景。支持在线音乐 API 搜索、多源 fallback、调用本地播放器播放网...

Security Scan

The skill mostly does what its description claims (bridges an MCP endpoint to local playback and a music API), but metadata and declared requirements are inconsistent and the code calls an external third‑party API and requires environment secrets that are not listed — this raises credential/exfiltration and trust concerns.

Purpose & Capability

The code implements an MCP music bridge consistent with the description (websocket MCP endpoint → bridge → music API → local player). However the package/registry metadata declared no required environment variables while the code requires MCP_ENDPOINT and MUSIC_API_KEY (plus optional MUSIC_SOURCE and PLAYER_CMD). That mismatch is an incoherence between what the skill claims and what it actually needs.

Instruction Scope

The SKILL.md instructions align with the code: it tells the user to set environment variables, install dependencies, and run the bridge. The instructions do not ask to read unrelated files or credentials. Note: the runtime will open a websocket to an external MCP endpoint and will call third‑party music API endpoints (api-v2.yuafeng.cn) — both are expected for this skill but imply you must trust those remote services.

Install Mechanism

There is no special installer; user is instructed to pip install the requirements.txt bundled with the skill. No arbitrary downloads or URL-based installers are present in the files provided.

Credentials

The code expects MCP_ENDPOINT and MUSIC_API_KEY (and may send MUSIC_API_KEY as an 'apikey' parameter to api-v2.yuafeng.cn). The registry metadata incorrectly lists no required env vars/credentials. Requiring an API key and connecting to a remote websocket is proportionate for a music bridge, but the metadata omission and the fact that the key is sent to a third‑party domain are notable risks — the user may unintentionally leak an API key to an unexpected host. PLAYER_CMD and MUSIC_SOURCE are also read from env but were not declared in metadata.

Persistence & Privilege

The skill is not always-enabled and uses normal autonomous invocation. It does not attempt to alter other skills or system-wide config. It spawns local processes (player, pkill/pause/resume) which is expected for local playback control; run-time privileges are limited to what the user process has.

What to consider before installing

This skill implements a local MCP-to-player music bridge and will: (1) open a websocket to whatever MCP_ENDPOINT you supply, (2) call third‑party music API endpoints (api-v2.yuafeng.cn) with your MUSIC_API_KEY, and (3) spawn local player processes (mpv by default) and use pkill to control them. Before installing: - Only connect to an MCP endpoint you trust; whatever endpoint you provide can instruct the bridged script to run the exposed tool operations. - Be aware MUSIC_API_KEY will be sent to api-v2.yuafeng.cn; confirm that domain is the intended music API provider or replace it with a provider you trust. - Registry metadata omitted required env vars (MCP_ENDPOINT, MUSIC_API_KEY, etc.); supply these deliberately and do not paste secrets from unrelated services. - Running this on a shared or production host can fetch remote audio and spawn processes; consider running in a sandbox/container and ensure mpv and pkill behavior is acceptable. - If you need higher assurance, review/replace the third‑party API URLs in music_mcp.py and audit the fastmcp dependency implementation before use.

简体中文 | English

---

简体中文

作用

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

架构

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

提供的工具

• play_music(query)
• play_music_index(query, n)
• stop_music()
• pause_music()
• resume_music()
• next_track()
• set_volume(level)
• music_info()

当前方案说明

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

启动

pip install -r requirements.txt
cp .env.example .env
python3 mcp_pipe.py music_mcp.py

环境变量

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

注意事项

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

---

English

Purpose

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

Architecture

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

Provided tools

• play_music(query)
• play_music_index(query, n)
• stop_music()
• pause_music()
• resume_music()
• next_track()
• set_volume(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

pip install -r requirements.txt
cp .env.example .env
python3 mcp_pipe.py music_mcp.py

Environment variables

• MCP_ENDPOINT: XiaoZhi MCP endpoint
• MUSIC_API_KEY: music API key
• MUSIC_SOURCE: 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.