← Projects
Spotify Minecraft Sync

Spotify MC Controller

Control Spotify playback directly from your Paper/Spigot Minecraft server — including custom jukebox disc support.

Java 21 Paper 1.21.1 Spotify Web API Work in Progress
View on GitHub Download .jar
🔐

OAuth Setup

Guided Spotify OAuth flow with an embedded HTTP callback server — no external redirect handler needed.

🎵

Playback Control

Play, pause, and search Spotify tracks with a single command from anywhere in the game.

💿

Custom Discs

Insert a custom-named jukebox disc and the plugin uses its display name as a Spotify search query.

🔄

Token Refresh

Access tokens are stored in config.yml and refreshed automatically — no repeated logins.

Commands

/spotify setup <clientId> <clientSecret> [redirectUri]

Save your Spotify app credentials. Optionally override the default redirect URI.

/spotify auth

Send a clickable authorization URL in chat. Click it, authorize the app, then return to the game.

/spotify play [query]

Without a query: resume current playback. With a query: search for the first matching track and play it.

/spotify pause

Pause the currently playing track on your linked Spotify account.

/spotify code <authorization_code>

Manual fallback — paste the authorization code directly if the callback redirect fails.

Requirements

  • ☕ Java 21
  • 📦 Paper / Spigot 1.21.1
  • 🔧 Maven 3.9+ (to build from source)
  • 🎧 Spotify Developer app with Client ID & Client Secret

Installation

  1. 1
    Open the Spotify Developer Dashboard, create an app, and add the redirect URI http://127.0.0.1:8000/api/spotify/callback.
  2. 2
    Download the shaded .jar from releases or build with mvn -DskipTests clean package.
  3. 3
    Place the jar in your server's plugins/ folder and start the server.
  4. 4
    Run /spotify setup <clientId> <clientSecret> then /spotify auth and click the link.

Build from Source

bash terminal 
mvn -DskipTests clean package

Output JAR is written to target/

Custom Disc Behavior

💿
Right-clicking a jukebox with a custom-named music disc cancels the default jukebox sound and uses the disc's display name as a Spotify search query.
🔇
Disc-triggered playback is silent in chat — no feedback messages are printed. Manual /spotify commands still show responses.
🎮
Vanilla disc names are ignored for Spotify search — only discs with a custom display name trigger playback.

How it Works

⚡
Spotify API calls run asynchronously — the server main thread is only touched for chat delivery, keeping performance impact minimal.
🌐
An embedded HTTP server handles the OAuth callback on http://127.0.0.1:8000/api/spotify/callback — no external infrastructure required.
💾
Tokens and credentials are persisted in config.yml under the spotify key. Access tokens are refreshed automatically before expiry.
🔑
If you change the Client ID, stored tokens are cleared and you must re-run /spotify auth to reauthorize.

Ready to bring Spotify into your server?

GitHub Download .jar