Which integrations are available for this server?

Allows controlling Spotify playback, searching for tracks/albums/playlists, managing devices, and adjusting playback settings like volume, shuffle, and repeat.

How do I use spotify-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@spotify-mcp-server Play Back in Black by AC/DC" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

spotify-mcp-server

by thebigredgeek

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Spotify MCP Server

Production-ready Model Context Protocol (MCP) server for Spotify with bulletproof error handling and token management.

Features

🔐 One-time OAuth authentication - Authenticate once, use forever (like spotifyd)
🛡️ Bulletproof error handling - Never invalidates tokens on transient failures
🔄 Automatic token refresh - Seamless refresh with concurrent request deduplication
💾 Atomic credential storage - Prevents corruption on process crash
⚡ Smart retry logic - Exponential backoff with rate limit handling
🎯 Conservative token management - Only clears credentials when provably invalid

Related MCP server: Spotify MCP Server

Example Usage

Once set up, you can control Spotify using natural language prompts with Claude:

🎵 Search & Discovery

"Search for AC/DC songs"
"Find albums by The Beatles"
"Search for rock playlists"
"Find tech podcasts"
"Search for The Beatles - show me tracks, albums, and playlists"

▶️ Playback Control

"Play Back in Black by AC/DC"
"Play the album Highway to Hell"
"Play my Discover Weekly playlist"
"Pause the music"
"Skip to the next song"
"Go back to the previous track"
"What's currently playing?"

🎚️ Advanced Controls

"Set volume to 50%"
"Turn on shuffle"
"Enable repeat"
"Set repeat to one song only"
"Turn off repeat"

📱 Device Management

"Show my Spotify devices"
"Switch playback to my phone"
"Transfer playback to my speaker"

All these operations work seamlessly with automatic token refresh, rate limiting, and error recovery.

Installation

BEFORE:

You need to set up a Spotify developer app to get a client id and secret. This will be used to authenticate the MCP server.

Method 1: Prompt-Based Setup (Easiest)

Install via Claude CLI and let Claude guide you through setup:

# Install the MCP server
claude mcp add --transport stdio spotify -- npx -y @tbrgeek/spotify-mcp-server

# Restart Claude Code
# (Fully quit and reopen)

The server starts without credentials and provides setup instructions when you need them. Simply ask Claude:

"Authenticate the spotify mcp server"

Claude will provide step-by-step setup instructions including:

Creating a Spotify app
Running the authentication script
Configuring credentials

See Prompt-Based Setup Guide below for details.

Method 2: Interactive Authentication (Stored Credentials)

For persistent credentials that survive restarts:

# Install globally
npm install -g @tbrgeek/spotify-mcp-server

# Run authentication
spotify-mcp-server auth

# Add to Claude Code config
claude mcp add --transport stdio spotify -- spotify-mcp-server

See Claude CLI Setup Guide for complete instructions.

Method 3: Environment Variables (Advanced)

For shared configurations or CI/CD:

# Set environment variables (see docs/CLAUDE_CLI_SETUP.md)
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REFRESH_TOKEN="your_refresh_token"
export SPOTIFY_ACCESS_TOKEN="your_access_token"

# Install with environment variables
claude mcp add --transport stdio spotify -- npx -y @tbrgeek/spotify-mcp-server

See Claude CLI Setup Guide for full environment variable setup.

Local Development

git clone https://github.com/thebigredgeek/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build
npm link

Setup

1. Create Spotify App

Go to Spotify Developer Dashboard
Create a new app
Note your Client ID and Client Secret
Add redirect URI: http://127.0.0.1:8888/callback

2. Authenticate

npm run auth

Follow the prompts to:

Enter your Client ID and Client Secret
Authorize in your browser
Credentials are saved to ~/.spotify-mcp/credentials.json

3. Configure MCP Client

Claude CLI / Claude Code (Recommended)

Edit ~/.claude/settings.local.json:

{
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "spotify-mcp-server"
    }
  }
}

Or use environment variables (see Claude CLI Setup Guide):

{
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tbrgeek/spotify-mcp-server"],
      "env": {
        "SPOTIFY_CLIENT_ID": "${SPOTIFY_CLIENT_ID}",
        "SPOTIFY_CLIENT_SECRET": "${SPOTIFY_CLIENT_SECRET}",
        "SPOTIFY_ACCESS_TOKEN": "${SPOTIFY_ACCESS_TOKEN}",
        "SPOTIFY_REFRESH_TOKEN": "${SPOTIFY_REFRESH_TOKEN}"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@tbrgeek/spotify-mcp-server"]
    }
  }
}

For local development:

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/opensource/spotify-mcp-server/dist/index.js"]
    }
  }
}

Prompt-Based Setup Guide

The easiest way to set up the Spotify MCP server is to install it first, then let Claude guide you through authentication.

Step 1: Install the Server

# Install via Claude CLI
claude mcp add --transport stdio spotify -- npx -y @tbrgeek/spotify-mcp-server

# Restart Claude Code (fully quit and reopen)

Step 2: Ask Claude for Setup Instructions

After restarting, ask Claude any of these questions:

"How do I set up Spotify?"
"Check Spotify health"
"Get Spotify authentication status"

Claude will respond with detailed setup instructions, including:

Creating a Spotify App:

Go to https://developer.spotify.com/dashboard
Click "Create app"
Fill in app name and redirect URI: http://127.0.0.1:8888/callback
Save your Client ID and Client Secret

Running Authentication:

# Install globally
npm install -g @tbrgeek/spotify-mcp-server

# Run authentication
spotify-mcp-server auth

The auth script will:

Prompt for your Client ID and Secret
Open your browser for authorization
Save credentials to ~/.spotify-mcp/credentials.json

Restart Claude Code - credentials are now loaded automatically!

Step 3: Verify

Ask Claude: "Check Spotify health"

You should see: ✅ Spotify MCP Server is authenticated and operational!

Manual Configuration

If you prefer to edit configuration files directly, here's how:

Option 1: Using Stored Credentials

Run authentication to generate credentials:

npm install -g @tbrgeek/spotify-mcp-server
spotify-mcp-server auth

Edit Claude Code config at ~/.claude/settings.local.json:

{
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "spotify-mcp-server"
    }
  }
}

Restart Claude Code - credentials are loaded from ~/.spotify-mcp/credentials.json

Option 2: Using Environment Variables

Get your credentials (run authentication once to obtain refresh token):
```
spotify-mcp-server auth
cat ~/.spotify-mcp/credentials.json
```

Set environment variables in your shell profile (~/.zshrc or ~/.bashrc):

export SPOTIFY_CLIENT_ID="your_client_id_here"
export SPOTIFY_CLIENT_SECRET="your_client_secret_here"
export SPOTIFY_ACCESS_TOKEN="your_access_token_here"
export SPOTIFY_REFRESH_TOKEN="your_refresh_token_here"

Edit Claude Code config at ~/.claude/settings.local.json:

{
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tbrgeek/spotify-mcp-server"],
      "env": {
        "SPOTIFY_CLIENT_ID": "${SPOTIFY_CLIENT_ID}",
        "SPOTIFY_CLIENT_SECRET": "${SPOTIFY_CLIENT_SECRET}",
        "SPOTIFY_ACCESS_TOKEN": "${SPOTIFY_ACCESS_TOKEN}",
        "SPOTIFY_REFRESH_TOKEN": "${SPOTIFY_REFRESH_TOKEN}"
      }
    }
  }
}

Reload your shell and restart Claude Code:
```
source ~/.zshrc  # or ~/.bashrc
```

Locating Config Files

Claude Code Config:

~/.claude/settings.local.json  # User-specific (not version-controlled)
~/.claude/settings.json         # Global defaults

Spotify Credentials:

~/.spotify-mcp/credentials.json  # Stored credentials (from auth script)

Editing Config:

# macOS/Linux
code ~/.claude/settings.local.json
# or
vim ~/.claude/settings.local.json

After editing any config:

Fully quit Claude Code (not just close window)
Reopen Claude Code to load new configuration

Architecture Highlights

Error Handling

The server implements a sophisticated error classification system that never invalidates tokens unless absolutely necessary:

✅ Never clears tokens for: 500/502/503, 429 (rate limit), network errors, timeouts
✅ Retries transient errors: 403 errors (Spotify bug), network failures
✅ Only clears tokens when: Refresh token returns invalid_grant

Token Management

Concurrent refresh deduplication: Multiple simultaneous API calls trigger only one token refresh
Refresh token preservation: Keeps existing refresh token if new one not returned (Spotify behavior)
5-minute expiry buffer: Refreshes tokens before they expire
Atomic writes: Credentials written to temp file, then atomically renamed

Retry Logic

Exponential backoff: 1s → 2s → 4s delays (configurable)
Rate limit handling: Respects Retry-After headers
Smart retries: Up to 3 attempts for transient failures

Development

See DEVELOPMENT.md for local testing, debugging, and publishing workflows.

Build

npm run build

Test

npm test

Lint

npm run lint

Project Status

Current Version: Fully functional Spotify control with comprehensive search and playback capabilities

✅ Implemented Features:

Core infrastructure with bulletproof error handling and token management
Comprehensive search (tracks, albums, playlists, podcasts)
Full playback control (play, pause, next, previous, volume)
Advanced playback features (shuffle, repeat modes, device management)
Multi-device support with transfer capabilities
Real-time playback state monitoring

🚀 Future Enhancements:

User library management (saved tracks, albums, playlists)
Playlist creation and editing
Recently played tracks
User top tracks and artists

License

MIT - see LICENSE

Author

Andrew Rhyne andrew.rhyne@shopify.com

Available Tools

3 tools

spotify_get_auth_statusA

Get authentication status and instructions for setting up Spotify credentials

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states it 'gets' information, implying a read operation, but lacks disclosure of any behavioral traits such as side effects, rate limits, or dependency on credentials being set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 10 words, extremely concise with no wasted words. It is front-loaded with the key action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description is largely complete. It covers the core purpose, though it could benefit from a brief note on the response format or highlighting differences from sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the baseline is 4. The description adds meaning by indicating the output includes both authentication status and setup instructions, which is valuable context beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves authentication status and setup instructions, using a specific verb and resource. It distinguishes from siblings like spotify_health_check and spotify_setup_instructions by combining both functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when authentication status or setup instructions are needed, but does not explicitly state when to use this tool versus alternatives like spotify_health_check or spotify_setup_instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spotify_health_checkB

Check if the Spotify MCP server is authenticated and operational

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It only says 'check' but does not disclose whether the tool is read-only, has side effects, or what defines 'operational'. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundant words, front-loaded with key information. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, and the description does not explain what the tool returns or possible states (e.g., success, error). Vague 'operational' leaves ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; schema coverage is 100%. The description adds context about what the check entails (authentication and operational status), adding value beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks authentication and operational status, using a specific verb ('check') and resource ('health'), distinguishing it from siblings like spotify_get_auth_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this vs alternative tools. The description does not mention when to prefer this over spotify_get_auth_status or spotify_setup_instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spotify_setup_instructionsA

Get detailed setup instructions for authenticating the Spotify MCP server

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It states that instructions are returned (read-only) but does not mention side effects, permissions, rate limits, or what the instructions contain. The description is minimal for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, clear sentence that front-loads the purpose without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and simple siblings, the description is adequate but lacks details such as prerequisites or the nature of the instructions. It could include hints about output format or steps covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and schema description coverage is 100% (trivially). The description does not need to add parameter meaning beyond the schema, and its clarity suffices.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides 'detailed setup instructions for authenticating the Spotify MCP server', specifying verb (get), resource (setup instructions), and purpose (authentication). It distinguishes from siblings like spotify_get_auth_status (status queries) and spotify_health_check (health checks).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when setup or authentication instructions are needed, but provides no explicit guidance on when to use this tool versus alternatives (e.g., after setup, use spotify_get_auth_status to verify). No when-not or alternative tool mentions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.1.0May 28, 2026
- First observedspotify_get_auth_status
- First observedspotify_health_check
- First observedspotify_setup_instructions

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored 2026-05-28 02:25 across 3 tools

Disambiguation1/5

All three tools — get_auth_status, health_check, and setup_instructions — serve nearly identical purposes related to authentication and server status. An agent would struggle to select the correct tool because they all provide information about setup or health with no distinct functional boundaries.

Naming Consistency3/5

All tools use snake_case with a 'spotify_' prefix, but the naming pattern is inconsistent: 'get_auth_status' follows a verb_noun pattern, while 'health_check' and 'setup_instructions' are noun_noun combinations, breaking the expected consistency.

Tool Count1/5

With only 3 tools, all dedicated to authentication and health, the server is vastly undersized for a Spotify service, which would typically require many tools for playback, search, queue management, etc. The count is far too low for the implied scope.

Completeness1/5

The tool surface covers only authentication and setup, missing core Spotify functionalities like play, pause, search, and playlist management. This is a severe gap that renders the server unable to perform any music-related tasks.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Spotify
io.github.akutishevsky
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Entertainment & Media App Automation
2
Spotify B
io.github.pipeworx-io
Spotify MCP — Web API via client_credentials OAuth
Entertainment & Media Search
422
spotify D
com.jojapi
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
Entertainment & Media Search
371
mytesla.ioOAuth
io.mytesla
Control your Tesla from your AI assistant - climate, charging, access, and security.
Home Automation & IoT Travel & Transportation
2

Related MCP Servers

MCP Spotify Server
Entertainment & Media Search
superseoworld
A
license
B
quality
D
maintenance
Enables interaction with Spotify's music catalog via the Spotify Web API, supporting searches, artist information retrieval, playlist management, and automatic token handling.
Updated 2 years ago (2025-03-03 12:50 UTC)
26
22 npm
23
MIT
Spotify MCP Server
Entertainment & Media App Automation Speech Processing
gentiku
F
license
Not graded
quality
Not graded
maintenance
Enables control of Spotify playback, music search, and playlist management through natural language commands. Available in both Python and Vercel implementations with comprehensive OAuth2 authentication and device management.
Updated a year ago (2025-09-20 03:13 UTC)
-
Spotify MCP Server
Entertainment & Media App Automation
nicklaustrup
A
license
Not graded
quality
D
maintenance
Enables interaction with Spotify through natural language for music discovery, playback control, library management, and playlist creation. Supports searching for music, controlling playback, managing saved tracks, and getting personalized recommendations based on mood and preferences.
Updated a year ago (2025-10-12 01:22 UTC)
53 npm
5
MIT
MCP Spotify Server
Entertainment & Media App Automation
fborello
A
license
A
quality
D
maintenance
Enables interaction with Spotify through LLMs using OAuth2 authentication. Supports music search, playback control, playlist management, and device management through natural language commands.
Updated 7 months ago (2026-02-18 21:23 UTC)
14
2
MIT