Music Player MCP

一个基于 Model Context Protocol 与 @modelcontextprotocol/ext-apps 的聊天内音乐播放器。它提供搜索播放与按歌曲 ID 播放两项工具，并返回可播放的音乐卡片数据。

这是一份可部署的源码，不附带网易云账号 Cookie、密钥、音乐文件、歌词或封面资源。使用者必须自行配置兼容的音乐数据 API，并自行遵守数据源与音乐版权方的条款。

它如何工作

1. 模型调用 play_music 搜索歌名，或调用 play_music_by_id 直接播放歌曲 ID。

2. MCP 向配置好的、Netease/网易云兼容 API 查询搜索结果、歌曲信息、封面、歌词与临时播放地址。

3. 服务将音频地址经受限的音频代理返回，播放器使用浏览器 <audio> 播放，支持暂停、拖动进度和歌词时间轴。

4. @modelcontextprotocol/ext-apps 客户端会读取工具的 widget 元数据，直接把 widget-src/music-player-widget.ts 构建出的界面渲染为卡片。

网易云的播放 URL 通常是临时的，约 20 分钟 后可能失效；这不是播放器永久保存的下载链接。失效后应重新调用播放工具获取新链接，而不是重试旧 URL。

Related MCP server: netease-mcp

工具

两项工具均可传入 color_primary、color_secondary 与 color_bg，自定义卡片颜色。

快速开始

需要 Python 3.11+、Node.js 20+，以及一个单独运行的 Netease-compatible API。

git clone <your-repository-url>
cd music-player-mcp

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

pip install -r requirements.txt
npm install
npm run build:widget

复制并修改环境变量：

cp .env.example .env

然后由你的进程管理器加载这些变量并启动：

python server.py

默认情况下，MCP 监听 127.0.0.1:3941，音频代理监听 127.0.0.1:3942。生产环境应使用 Nginx 或 Caddy 暴露 HTTPS 路径，示例见 部署说明。

客户端兼容性

支持 MCP Apps / ext-apps 的客户端

将公开的 streamable HTTP MCP 地址添加为连接器即可。只要客户端能够识别 @modelcontextprotocol/ext-apps 和工具的 output template，它会自动渲染播放器 widget，不需要再写前端页面。

自己写的聊天前端

普通网页聊天不会因为“连接了 MCP”就自动拥有卡片组件。它需要读取工具结果，并将其转换为自己的音乐消息卡片；数据结构和推荐接入方式见 自定义前端适配。

你不需要开源自己的整套聊天应用。把这份 MCP 服务开源，再提供这一页适配说明即可。

安全与发布前检查

• .env、Cookie 文件、访问令牌与私有域名均不应提交。

• 本项目的音频代理只允许 ALLOWED_AUDIO_HOST_SUFFIXES 中的域名，避免成为任意 URL 的开放代理。

• 不要把音频、歌词、封面或歌曲目录打包进仓库；均应由运行时请求得到。

• 发布 GitHub 前请自行选择并添加许可证文件；当前仓库未预设许可证。

开发结构

server.py                         # FastMCP、音乐数据请求与受限音频代理
widget-src/music-player-widget.ts # ext-apps 播放器源码
scripts/build-widget.mjs          # 构建 dist/widget/ 的脚本
docs/                             # 部署与自定义前端接入说明