upnext

upnext-mcp

为你的设备音频打造的 MCP 服务。 Spotify、浏览器、本地文件和当前正在播放的内容，共用一个队列。

{
  "mcpServers": {
    "upnext": {
      "command": "npx",
      "args": ["-y", "upnext-mcp", "--library", "/Users/me/Music"]
    }
  }
}

把它添加到 Claude Desktop、Cursor、Windsurf 或其他任何支持 MCP 的工具中。

它能让 Agent 做什么

you:  what am I listening to?
      → ❚❚ Acquired — Jensen Huang (Google Chrome)

you:  let that finish, then play Bad Habit
      → adopted "Acquired — Jensen Huang" as q_0001
        up next:
          q_0001  Acquired — Jensen Huang
          q_0002  Bad Habit — Steve Lacy

第一行读取浏览器标签页——无需扩展程序。第二行将其作为真正的条目加入队列，因此 Agent 会在用户正在做的事情上继续添加，而不是打断它。

工具

工具
media_now	正在播放什么，包括队列中和设备其他位置的内容
media_queue	队列，以及每个条目的 ID
media_enqueue	添加链接、文件路径、Spotify URI 或普通描述
media_play · media_pause · media_next	播放控制
media_seek	跳转到指定位置——如果来源不支持，会明确说明
media_move · media_remove	按 ID 调整顺序和移除条目
media_search	搜索支持搜索的来源
media_adopt_current	将当前正在播放的内容加入队列
media_setup	查看此处已接入的内容及其功能

所有变更都通过 ID 指定对象，且每个响应都包含带 ID 的队列。这是刻意设计的：如果模型根据位置操作，任何其他对队列的操作都会造成竞态；等它的调用执行时，位置 2 可能已经是另一首歌。

如实告知模型

有两种情况的行为不同于大多数工具服务，原因相同——如果模型遇到悄无声息的无操作，就会信誓旦旦地告诉用户操作成功了。

当来源不支持跳转时调用 media_seek，返回一句说明，而不是错误：

当前来源（spotify-desktop）不支持跳转。未做任何更改。

没有可搜索的来源时调用 media_search，会说明原因：

未找到“bad habit”。 正在播放的来源：spotify-desktop、nowplaying、local 无法匹配标题：此处没有已接入的搜索功能……

标题需要搜索器

链接会明确指定要播放什么。描述则需要查询，但并非每个后端都能做到。Spotify 桌面应用可以播放交给它的 URI，却无法搜索曲库——因此，在普通的 Mac 设置中，media_enqueue 无法将 "bad habit" 匹配到任何内容。

为它添加以下任意一项：

// index a music folder
"args": ["-y", "upnext-mcp", "--library", "/Users/me/Music"]

// or a Spotify Web token, via the environment
"env": { "SPOTIFY_TOKEN": "..." }

media_setup 会告诉你已经接入了哪些服务。

嵌入使用

如果你的产品已经有队列，请直接公开现有队列，而不是另建一个与之争用的队列：

import { createServer } from 'upnext-mcp';
import { serveStdio } from '@modelcontextprotocol/server/stdio';

serveStdio(() => createServer(myExistingRuntime));

这个包只负责传输——排序、能力协商、解析和协调都由 upnext-core 处理。它独立存在，因为传输层本身带有主观看法，不该让任何导入运行时的项目继承这一套。

---

完整文档：https://github.com/tothienbao6a0/upnext · Apache-2.0