Upnext

One audio queue across Spotify, the browser, local files and whatever is already playing.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "upnext": {
      "command": "npx",
      "args": [
        "-y",
        "upnext"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

upnext

One queue over every audio source — including the ones you don't control.

A library your product imports so that whatever is driving — a model, a person clicking, a script — can control audio without knowing whether the sound is coming from Spotify, a browser tab, a podcast feed, or a file on disk.

server.ts

const runtime = new Runtime({ adapters: [spotify, browser, local, nowPlaying] });

runtime.enqueue(NOW_PLAYING_URI);                         // the podcast already
                                                          // playing in their browser
runtime.enqueue('spotify:track:1OWBh1eVxUdA1Z6UA8r4nh');  // then a Spotify track
runtime.enqueue('https://example.com/episode.mp3');       // then a file on the web
runtime.enqueue('something calmer after those');          // then whatever you decide, later

await runtime.play();

Four sources, one list, in order. The first one is playing inside an app you do not own — and the queue waits for it to finish before taking over.

What you get

Add audio to your product without marrying one service. Write against one queue; swap or add backends later. An entry describes what to play, not where from, so it can bind to whichever source is available at the moment it plays.

Join what someone is already listening to instead of talking over it. The machine's current playback — a YouTube tab, a podcast in Safari, VLC — can be a queue entry like any other. Your track starts when theirs ends.

Know what you can do before you try it. runtime.can('seek') answers for the backend that is actually loaded. No silent no-ops, no discovering at 2am that one source quietly ignored a command.

Keep playing when a source fails. If a backend cannot load an entry, the same description is handed to the next one that can. A queue does not stop because one service is down.

Survive a restart. serialize() / restore() — and a queue saved on a machine with Spotify reopens on one without it, then plays from somewhere else.

What ships today

package	plays
`upnext-core`	nothing — the queue, state machine, capability model and events. Zero dependencies, no I/O.
`upnext-adapter-spotify`	the Spotify desktop app on macOS with no credentials, or the Web API with a token you hold
`upnext-adapter-browser`	any media element you control — browser, Electron renderer, webview, across a process boundary
`upnext-adapter-local`	local files and streams via `ffplay`/`afplay`
`upnext-adapter-apple-music`	your Apple Music library through the Music app — no credentials, and it can search
`upnext-adapter-nowplaying`	whatever the machine is already playing, whichever app is playing it (macOS + Linux)
`upnext-adapter-process`	an adapter written in any language, over a pipe
`upnext-desktop`	all of the above wired for you, in one call — plus the `upnext` CLI
`upnext-mcp`	the same, as an MCP server any agent can use
`upnext-http`	the same, over HTTP with a live event stream

What each one can actually do

The point of the capability model is that these differ, and say so:

	starts tracks	end of track	position	seek	pause	volume	search	someone else can change it
browser	✅	`event`	exact	✅	✅	✅	❌	no
local (ffplay)	✅	`event`	estimated	✅	✅	❌	✅¹	no
local (afplay)	✅	`event`	estimated	❌	✅	❌	✅¹	no
spotify desktop	✅	`event`	exact	✅	✅	✅	❌²	yes
spotify web	✅	`event`	exact	✅	✅	✅	✅	yes
apple music	✅	`poll`	exact	✅	✅	✅	✅	yes
nowplaying	❌³	`poll`	exact	❌	✅	❌	❌	yes

¹ only when you point it at a music folder to index · ² the AppleScript dictionary cannot search a catalogue · ³ there is no way to ask macOS's Now Playing register to start a specific track

Every ❌ there is a refusal rather than a silent failure. An adapter that claims it can seek and then doesn't is a bug you chase for an hour; these tell you first, and the runtime routes around them.

Not built yet: Now Playing on Windows, and controlling one specific browser tab (needs an extension). Details at the bottom.

The problem

Every audio integration today puts the queue in the wrong place.

Code

   WITHOUT upnext                          WITH upnext

   caller                                  caller
     │                                       │
     │ "play X"                              │ enqueue / move / skip
     ▼                                       ▼
   Spotify Web API                     ┌───────────────┐
     │                                 │   THE QUEUE   │ ← yours. one of them.
     ▼                                 └───────┬───────┘
   ┌───────────────┐                           │
   │ Spotify queue │ ← the real one    ┌───────┼───────┬────────┐
   └───────────────┘                   ▼       ▼       ▼        ▼
                                    Spotify  Apple  browser   local
   Now queue a YouTube video.                 Music    tab      file
   Nowhere to put it.               Each one just plays what it's handed.

That works right up until the next item isn't a Spotify track — and then there is nowhere to put it. upnext inverts it: the runtime owns the queue, and Spotify's queue, Apple Music's Up Next and a browser tab's <audio> element all become places to send one item at a time.

Quickstart

The fast way — every source this machine can reach, one call:

Terminal

npm i upnext-desktop

server.ts

import { desktop } from 'upnext-desktop';

const audio = await desktop();
audio.enqueue('spotify:track:1OWBh1eVxUdA1Z6UA8r4nh');
audio.enqueue('https://example.com/podcast.mp3');
await audio.play();

It ships a CLI too:

Code

$ upnext now
▶ Korea's STRANGEST Food is on Jeju Island!! — More Best Ever Food Review Show
  Google Chrome · 23:20 / 24:11

That is a YouTube tab, read with no browser extension.

Or give it to an agent

config.json

{ "mcpServers": { "upnext": { "command": "npx", "args": ["-y", "upnext-mcp"] } } }

Twelve tools in Claude Desktop, Cursor or anything else that speaks MCP — including media_adopt_current, which puts what someone is already listening to into the queue so the agent adds to it rather than talking over it.

Or wire it yourself

Terminal

npm i upnext-core upnext-adapter-local

upnext-adapter-local needs ffplay (from ffmpeg) or afplay (built into macOS).

server.ts

import { Runtime } from 'upnext-core';
import { LocalAdapter } from 'upnext-adapter-local';

const runtime = new Runtime({
  // Absolute paths only — Node does not expand `~`.
  adapters: [new LocalAdapter({ library: ['/Users/you/Music'] })],
});

runtime.on('item:started', ({ item }) => console.log('▶', item.ref.title));
runtime.on('item:ended',   ({ item }) => console.log('■', item.ref.title));

runtime.enqueue('file:///path/to/first.mp3');
runtime.enqueue('file:///path/to/second.mp3');

await runtime.play();     // plays the first, then the second, on its own
await runtime.next();     // skip

On a Mac with Spotify open, add a second source with nothing to sign up for:

Terminal

npm i upnext-adapter-spotify

server.ts

import { SpotifyDesktopAdapter } from 'upnext-adapter-spotify';

const runtime = new Runtime({
  adapters: [new LocalAdapter({ library: ['/Users/you/Music'] }), new SpotifyDesktopAdapter()],
});

runtime.enqueue('https://open.spotify.com/track/1OWBh1eVxUdA1Z6UA8r4nh');
runtime.enqueue('file:///path/to/second.mp3');
await runtime.play();   // Spotify, then a local file, without either knowing

Want to hear it right now, with no files of your own?

bash

git clone https://github.com/tothienbao6a0/upnext && cd upnext
npm install && npm run demo    # synthesizes its own tones and plays them

How it works

The pieces

Code

                          your application
                                │
   ┌────────────────────────────┼────────────────────────────┐
   │  Runtime                   ▼                            │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐     │
   │  │  Queue   │  │    Binder    │  │   Prefetcher   │     │
   │  │ ordered  │  │ which source │  │  resolve ahead │     │
   │  │ id-based │  │  + fallback  │  │  of the head   │     │
   │  └──────────┘  └──────────────┘  └────────────────┘     │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐     │
   │  │   Deck   │  │   Watcher    │  │   Reconciler   │     │
   │  │  loaded  │  │  is it over  │  │  human took    │     │
   │  │   item   │  │     yet?     │  │      over      │     │
   │  └──────────┘  └──────────────┘  └────────────────┘     │
   └────────────────────────────┬────────────────────────────┘
                                │  Adapter interface
    ┌──────────┬──────────┬────────┴───┬──────────┬──────────┐
    ▼          ▼          ▼            ▼          ▼          ▼
 Spotify    Spotify    a media      local     whatever    anything
 desktop    Web API     element     files      is on      you write
                     (browser /              (macOS Now
                      Electron)               Playing)

The life of one queue entry

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Upnext

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "upnext": { "command": "npx", "args": ["-y", "upnext"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/upnext?style=directory)](https://allmcps.com/mcp/upnext)

HTML Embed

<a href="https://allmcps.com/mcp/upnext"><img src="https://allmcps.com/api/badge/upnext?style=directory" alt="Upnext on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Upnext →Install in Claude Desktop Install in Cursor Install in VS Code

Upnext

One audio queue across Spotify, the browser, local files and whatever is already playing.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "upnext": {
      "command": "npx",
      "args": [
        "-y",
        "upnext"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

upnext

One queue over every audio source — including the ones you don't control.

server.ts

const runtime = new Runtime({ adapters: [spotify, browser, local, nowPlaying] });

runtime.enqueue(NOW_PLAYING_URI);                         // the podcast already
                                                          // playing in their browser
runtime.enqueue('spotify:track:1OWBh1eVxUdA1Z6UA8r4nh');  // then a Spotify track
runtime.enqueue('https://example.com/episode.mp3');       // then a file on the web
runtime.enqueue('something calmer after those');          // then whatever you decide, later

await runtime.play();

Four sources, one list, in order. The first one is playing inside an app you do not own — and the queue waits for it to finish before taking over.

What you get

Know what you can do before you try it. runtime.can('seek') answers for the backend that is actually loaded. No silent no-ops, no discovering at 2am that one source quietly ignored a command.

Keep playing when a source fails. If a backend cannot load an entry, the same description is handed to the next one that can. A queue does not stop because one service is down.

Survive a restart. serialize() / restore() — and a queue saved on a machine with Spotify reopens on one without it, then plays from somewhere else.

What ships today

package	plays
`upnext-core`	nothing — the queue, state machine, capability model and events. Zero dependencies, no I/O.
`upnext-adapter-spotify`	the Spotify desktop app on macOS with no credentials, or the Web API with a token you hold
`upnext-adapter-browser`	any media element you control — browser, Electron renderer, webview, across a process boundary
`upnext-adapter-local`	local files and streams via `ffplay`/`afplay`
`upnext-adapter-apple-music`	your Apple Music library through the Music app — no credentials, and it can search
`upnext-adapter-nowplaying`	whatever the machine is already playing, whichever app is playing it (macOS + Linux)
`upnext-adapter-process`	an adapter written in any language, over a pipe
`upnext-desktop`	all of the above wired for you, in one call — plus the `upnext` CLI
`upnext-mcp`	the same, as an MCP server any agent can use
`upnext-http`	the same, over HTTP with a live event stream

What each one can actually do

The point of the capability model is that these differ, and say so:

	starts tracks	end of track	position	seek	pause	volume	search	someone else can change it
browser	✅	`event`	exact	✅	✅	✅	❌	no
local (ffplay)	✅	`event`	estimated	✅	✅	❌	✅¹	no
local (afplay)	✅	`event`	estimated	❌	✅	❌	✅¹	no
spotify desktop	✅	`event`	exact	✅	✅	✅	❌²	yes
spotify web	✅	`event`	exact	✅	✅	✅	✅	yes
apple music	✅	`poll`	exact	✅	✅	✅	✅	yes
nowplaying	❌³	`poll`	exact	❌	✅	❌	❌	yes

¹ only when you point it at a music folder to index · ² the AppleScript dictionary cannot search a catalogue · ³ there is no way to ask macOS's Now Playing register to start a specific track

Not built yet: Now Playing on Windows, and controlling one specific browser tab (needs an extension). Details at the bottom.

The problem

Every audio integration today puts the queue in the wrong place.

Code

   WITHOUT upnext                          WITH upnext

   caller                                  caller
     │                                       │
     │ "play X"                              │ enqueue / move / skip
     ▼                                       ▼
   Spotify Web API                     ┌───────────────┐
     │                                 │   THE QUEUE   │ ← yours. one of them.
     ▼                                 └───────┬───────┘
   ┌───────────────┐                           │
   │ Spotify queue │ ← the real one    ┌───────┼───────┬────────┐
   └───────────────┘                   ▼       ▼       ▼        ▼
                                    Spotify  Apple  browser   local
   Now queue a YouTube video.                 Music    tab      file
   Nowhere to put it.               Each one just plays what it's handed.

Quickstart

The fast way — every source this machine can reach, one call:

Terminal

npm i upnext-desktop

server.ts

import { desktop } from 'upnext-desktop';

const audio = await desktop();
audio.enqueue('spotify:track:1OWBh1eVxUdA1Z6UA8r4nh');
audio.enqueue('https://example.com/podcast.mp3');
await audio.play();

It ships a CLI too:

Code

$ upnext now
▶ Korea's STRANGEST Food is on Jeju Island!! — More Best Ever Food Review Show
  Google Chrome · 23:20 / 24:11

That is a YouTube tab, read with no browser extension.

Or give it to an agent

config.json

{ "mcpServers": { "upnext": { "command": "npx", "args": ["-y", "upnext-mcp"] } } }

Or wire it yourself

Terminal

npm i upnext-core upnext-adapter-local

upnext-adapter-local needs ffplay (from ffmpeg) or afplay (built into macOS).

server.ts

import { Runtime } from 'upnext-core';
import { LocalAdapter } from 'upnext-adapter-local';

const runtime = new Runtime({
  // Absolute paths only — Node does not expand `~`.
  adapters: [new LocalAdapter({ library: ['/Users/you/Music'] })],
});

runtime.on('item:started', ({ item }) => console.log('▶', item.ref.title));
runtime.on('item:ended',   ({ item }) => console.log('■', item.ref.title));

runtime.enqueue('file:///path/to/first.mp3');
runtime.enqueue('file:///path/to/second.mp3');

await runtime.play();     // plays the first, then the second, on its own
await runtime.next();     // skip

On a Mac with Spotify open, add a second source with nothing to sign up for:

Terminal

npm i upnext-adapter-spotify

server.ts

import { SpotifyDesktopAdapter } from 'upnext-adapter-spotify';

const runtime = new Runtime({
  adapters: [new LocalAdapter({ library: ['/Users/you/Music'] }), new SpotifyDesktopAdapter()],
});

runtime.enqueue('https://open.spotify.com/track/1OWBh1eVxUdA1Z6UA8r4nh');
runtime.enqueue('file:///path/to/second.mp3');
await runtime.play();   // Spotify, then a local file, without either knowing

Want to hear it right now, with no files of your own?

bash

git clone https://github.com/tothienbao6a0/upnext && cd upnext
npm install && npm run demo    # synthesizes its own tones and plays them

How it works

The pieces

Code

                          your application
                                │
   ┌────────────────────────────┼────────────────────────────┐
   │  Runtime                   ▼                            │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐     │
   │  │  Queue   │  │    Binder    │  │   Prefetcher   │     │
   │  │ ordered  │  │ which source │  │  resolve ahead │     │
   │  │ id-based │  │  + fallback  │  │  of the head   │     │
   │  └──────────┘  └──────────────┘  └────────────────┘     │
   │  ┌──────────┐  ┌──────────────┐  ┌────────────────┐     │
   │  │   Deck   │  │   Watcher    │  │   Reconciler   │     │
   │  │  loaded  │  │  is it over  │  │  human took    │     │
   │  │   item   │  │     yet?     │  │      over      │     │
   │  └──────────┘  └──────────────┘  └────────────────┘     │
   └────────────────────────────┬────────────────────────────┘
                                │  Adapter interface
    ┌──────────┬──────────┬────────┴───┬──────────┬──────────┐
    ▼          ▼          ▼            ▼          ▼          ▼
 Spotify    Spotify    a media      local     whatever    anything
 desktop    Web API     element     files      is on      you write
                     (browser /              (macOS Now
                      Electron)               Playing)

The life of one queue entry

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Upnext

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "upnext": { "command": "npx", "args": ["-y", "upnext"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/upnext?style=directory)](https://allmcps.com/mcp/upnext)

HTML Embed

<a href="https://allmcps.com/mcp/upnext"><img src="https://allmcps.com/api/badge/upnext?style=directory" alt="Upnext on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Upnext →Install in Claude Desktop Install in Cursor Install in VS Code