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 类继承基类即可。

数据流很简单:用户通过前端下达指令 → 服务器通过插件获取元数据或音频流 → 服务器将音频直接推送给目标音箱(不经过前端)。

Music Assistant architecture diagram with clients, server and speakers

开发者最该关注的部分:API

项目文档里没有正式标注“API Reference”,但通过前端源码和 mass Python 库(music-assistant-client)可以摸清接口规律。核心端点:

bash
1 2 3 4 5 6 7 8 9
# 获取所有播放器
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。

python
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
# 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 的成本极低,而且效果立竿见影。项目今天爆星,说明很多人看到了这个需求,我建议你趁社区还没成熟抓紧上手,等稳定了生态更健全时,自己手里已经有成熟方案了。

(完)