Music Assistant 今天在 GitHub 上拿了接近 2000 个 star,我翻了一下仓库,发现它不是又一个播放器,而是一个音乐中心化服务:聚合多种流媒体源(Spotify、Tidal、Qobuz、本地文件),统一推送到不同品牌的音箱(Sonos、AirPlay、Chromecast、DLNA、Squeezebox 等)。服务器端用 Python 写,可以跑在树莓派、NAS 或任何常开设备上。
开发者更关心的是:这个东西能不能编程控制?API 好不好用?能不能接到我现在的自动化或 AI 工作流里?下面直接说答案:原生没有 MCP Server,但它的 REST API + WebSocket 事件系统足够简单,自己写一个 MCP Server 只需要一晚上。
架构与核心设计
Music Assistant 采用经典的 C/S 模型:
- 服务器(
server仓库)负责管理播放队列、与流媒体服务通信、驱动音箱。 - 前端(
frontend仓库)是一个 Vue 3 + Vite 的 SPA,通过 HTTP 与 WebSocket 连接服务器。 - 插件系统:每种音源(Provider)和每种音箱(Player Provider)都是插件,Python 类继承基类即可。
数据流很简单:用户通过前端下达指令 → 服务器通过插件获取元数据或音频流 → 服务器将音频直接推送给目标音箱(不经过前端)。

开发者最该关注的部分:API
项目文档里没有正式标注“API Reference”,但通过前端源码和 mass Python 库(music-assistant-client)可以摸清接口规律。核心端点:
# 获取所有播放器
GET http://<server>:8095/api/players
# 获取当前播放队列
GET http://<server>:8095/api/players/<player_id>/queue
# 播放指定媒体
POST http://<server>:8095/api/players/<player_id>/play_media
Body: {"uri": "spotify://track/xxx", "enqueue": false}
WebSocket 地址为 /ws,会推送播放状态变化、队列更新等事件。这些 API 未版本化,但比较稳定——我测了本地实例,curl 直接可用。安全方面:默认无认证,官方建议用反向代理加 Auth。
实战:基于 Music Assistant API 构建 MCP Server
这里假设你的 AI Agent(比如 Claude)想控制家里的音响。我会用 Python 写一个 MCP Server,暴露三个工具:search_media、play_uri、get_current_track。
# mcp_music_assistant.py
from mcp import Server, Tool
import httpx, json
MAS_HOST = "http://192.168.1.100:8095"
_player_id = None # 可以固定或通过工具传入
async def list_players():
async with httpx.AsyncClient() as client:
resp = await client.get(f"{MAS_HOST}/api/players")
return resp.json()
server = Server("music-assistant")
@server.tool("search_media")
async def search_media(query: str, limit: int = 5) -> list:
"""搜索曲库中的音乐、专辑、艺术家"""
async with httpx.AsyncClient() as client:
resp = await client.get(f"{MAS_HOST}/api/search", params={"query": query, "limit": limit})
return resp.json().get("results", [])
@server.tool("play_uri")
async def play_uri(uri: str, player_id: str = None):
"""在指定播放器上播放某个 URI(如 spotify://track/xxx)"""
pid = player_id or _player_id
async with httpx.AsyncClient() as client:
resp = await client.post(f"{MAS_HOST}/api/players/{pid}/play_media",
json={"uri": uri, "enqueue": False})
return {"status": resp.status_code}
@server.tool("current_track")
async def current_track(player_id: str = None) -> dict:
"""获取当前播放信息"""
pid = player_id or _player_id
async with httpx.AsyncClient() as client:
resp = await client.get(f"{MAS_HOST}/api/players/{pid}/queue/current")
return resp.json()
# 启动 MCP Server(stdin/stdout 模式,适配 Claude Desktop)
server.run()
这个原型用了 mcp Python 库(pip install mcp)。配置到 Claude Desktop 的 mcpServers 后,你就可以说:“下一首”、“搜索周杰伦的歌”、“现在放的是什么” —— 你的指令会变成 API 调用,控制 Music Assistant 播放。
需要注意:当前 Music Assistant 没有官方的安全层,暴露 API 到公网有风险;建议只在内网使用,或者配合 API Key 反向代理。
同类工具对比
| 项目 | 架构 | 流媒体支持 | 设备兼容 | API 开放度 | MCP 集成 |
|---|---|---|---|---|---|
| Music Assistant | C/S + 插件 | 多(含本地) | 极广 | REST + WS | 需自建 |
| Navidrome | C/S | 仅本地 | 无 | Subsonic API | 无需(已有 Subsonic MCP) |
| Plex | C/S | 多(需 Plex Pass) | 少 | 不全开放 | 暂无 |
| Roon | 收费 C/S | 流媒体+Tidal | 专用设备 | SDK 需申请 | 无 |
Music Assistant 最大的优势是设备兼容性:它甚至能驱动一些老旧的 Squeezebox 和 Denon HEOS。缺点也很明显:文档不全、API 无版本、社区规模小(1800+ stars 算小而美)。如果你是开发者,愿意自己读源码,这个项目很有潜力。
我的判断与建议
- 适合谁:家里有多品牌音箱、想统一控制的人;做智能家居自动化(Home Assistant 集成已存在);想自己写 MCP 工具连接 AI 的开发者。
- 不适合谁:只想听本地文件、设备单一的,Navidrome + 随便一个客户端更轻量。
- 避坑指南:默认端口 8095,记得改;WebSocket 事件没文档,对照前端源码看;某些流媒体插件(如 Apple Music)需要额外配置。
如果你想用 AI 控制家庭音乐,Music Assistant 是目前最值得投入时间的基础设施——API 简单直接,写一个 MCP Server 的成本极低,而且效果立竿见影。项目今天爆星,说明很多人看到了这个需求,我建议你趁社区还没成熟抓紧上手,等稳定了生态更健全时,自己手里已经有成熟方案了。
(完)