Skip to main content
Glama
Sign In
spotifyMCP

spotifyMCP

by real-kijmoshi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript

spotifyMCP

MCP server for Spotify. Control playback, manage playlists, search music, and more — from any MCP-compatible AI client.

34 tools. 2 dependencies. Works locally or on a server.

Quick Start

git clone https://github.com/real-kijmoshi/SpotifyMCP.git
cd spotifyMCP
npm install    # or bun install
npm run setup  # or bun run setup

The setup script will:

  1. Show you where to get a Spotify Developer app

  2. Ask for your Client ID, Secret (optional), port, and webhook URL

  3. Generate an API key to protect your server from unauthorized access

  4. Open Spotify authorization in your browser

  5. Handle the OAuth callback automatically

  6. Optionally start the server with a public tunnel (cloudflared) and run it as a background service (pm2)

Related MCP server: Spotify MCP Server

Connect to Claude Desktop

Add one of these to claude_desktop_config.json:

Local (stdio):

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/spotifyMCP/src/index.js", "--stdio"]
    }
  }
}

HTTP (local or remote):

{
  "mcpServers": {
    "spotify": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Via tunnel (public URL):

{
  "mcpServers": {
    "spotify": {
      "url": "https://your-tunnel.trycloudflare.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Running

# Local stdio mode (for Claude Desktop)
node src/index.js --stdio

# HTTP server on port 3000
node src/index.js --port 3000

# HTTP server with public tunnel
node src/index.js --port 3000 --tunnel

# As a pm2 background service with tunnel
npm run service:install

Service Management

npm run service:logs       # view logs (shows tunnel URL)
npm run service:status     # check status
npm run service:restart    # restart
npm run service:stop       # stop
npm run service:remove     # remove service

Getting a Spotify Client ID

  1. Go to developer.spotify.com/dashboard

  2. Log in with your Spotify account

  3. Click Create App

  4. Set a name (e.g. "spotifyMCP") and description

  5. Add Redirect URI: http://127.0.0.1:3080/callback (local) or the HTTPS URL shown during setup (server)

  6. Click Save

  7. Copy your Client ID from the app settings page

Server Setup

When running on a remote server, the setup automatically starts a cloudflared tunnel for the OAuth callback. This gives you a real HTTPS URL (e.g. https://xxxx.trycloudflare.com/callback) that Spotify accepts.

  • cloudflared must be installed (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)

  • The tunnel starts on port 3080, gets a temporary HTTPS URL, then closes after auth completes

  • No self-signed certs, no SSH tunnels needed

Tools (34)

Playback

Tool

Description

playback_state

Get current playback state

playback_now_playing

Get currently playing track

playback_play

Start or resume playback

playback_pause

Pause playback

playback_next

Skip to next track

playback_previous

Skip to previous track

playback_seek

Seek to position (ms)

playback_volume

Set volume (0-100)

playback_shuffle

Toggle shuffle mode

playback_repeat

Set repeat mode

playback_transfer

Transfer to another device

Search

Tool

Description

search

Search tracks, artists, albums, playlists

search_tracks

Search tracks only

search_artists

Search artists only

search_albums

Search albums only

search_playlists

Search playlists only

Playlists

Tool

Description

playlists_list

List your playlists

playlists_get

Get playlist and its tracks

playlists_create

Create a new playlist

playlists_add_tracks

Add tracks to playlist

playlists_remove_tracks

Remove tracks from playlist

playlists_follow

Follow/save a playlist

Profile & Discovery

Tool

Description

user_profile

Get your Spotify profile

user_top_tracks

Get your top tracks

user_top_artists

Get your top artists

user_devices

List available devices

user_recently_played

Get recently played tracks

Library

Tool

Description

library_saved_tracks

List saved/liked tracks

library_saved_albums

List saved albums

library_check_tracks

Check if tracks are in library

library_save_tracks

Save tracks to library

library_remove_tracks

Remove tracks from library

Queue

Tool

Description

queue_get

Get current playback queue

queue_add

Add track to queue

Architecture

spotifyMCP/
├── setup.js              # Interactive quickstart CLI
└── src/
    ├── index.js          # Entry point (--stdio or --port N --tunnel)
    ├── create-server.js  # McpServer factory + tool registration
    ├── http-handler.js   # node:http + StreamableHTTPServerTransport
    ├── tunnel.js         # Auto-detect cloudflared / localtunnel
    ├── auth/
    │   ├── oauth.js      # PKCE generation, token exchange/refresh
    │   ├── auth-server.js # Ephemeral OAuth callback server
    │   └── token-store.js # .spotify-auth.json persistence
    ├── spotify/
    │   └── api.js        # Spotify Web API fetch wrapper
    └── tools/            # 7 tool modules, 34 tools total

Config (.env)

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=optional
REDIRECT_URI=http://127.0.0.1:3080/callback
MCP_PORT=3000
MCP_API_KEY=auto_generated_key
LOCATION=local
# SERVER_IP=10.0.0.5
# WEBHOOK_URL=

Authentication

When running in HTTP mode (especially with a public tunnel), the server is protected by an API key. The setup script generates one automatically.

For Claude Desktop, add the headers field:

{
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

The API key is required for all HTTP requests. Stdio mode (local) does not use API key auth since it's already protected by process isolation.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    This server cannot be deployed

    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

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Spotify MCP Server

      Yonsn76
      F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to control Spotify playback, search for music, manage playlists, and access library information through the Spotify API. Requires Spotify Premium for playback control features.
      4
      -

    • Spotify MCP Server (Python)

      argotdev
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Spotify through MCP, providing tools for searching tracks, artists, albums, playlists, and accessing user data like top tracks and recently played.
      -

    • spotify-mcp-server

      freddy24-7
      F
      license
      A
      quality
      D
      maintenance
      Exposes Spotify controls as MCP tools for playback, playlist management, and AI playlist generation; includes a web app and supports multi-user profiles.
      14
      -