Spotify MCP Server
A Node.js-based server that integrates with the Spotify Web API and the Model Context Protocol (MCP) to provide tools for searching, controlling playback, and managing Spotify content. It allows users to interact with their Spotify account programmatically via a standardized MCP interface over stdio transport.
🧠 Project Overview
Name: Spotify MCP Server
Description: A programmable interface that connects Spotify Web API with the MCP standard, enabling search, playback control, and playlist management using JSON-based tools over stdio.
Key Features:
- 🔍 Search for tracks on Spotify
- 🎵 Check current playback state
- ▶️ Play specific tracks by URI
- 📋 Retrieve user playlists
- ⏸ Pause ongoing playback
- 🔐 OAuth authentication with Spotify
- 📉 Rate limit handling for Spotify API requests
⚙️ Prerequisites
- Node.js (v16 or higher recommended)
- A Spotify Developer Account with app credentials
- npm (Node Package Manager)
📦 Installation Steps
# 1. Clone the repository
git clone <repository-url>
cd spotify-mcp
# 2. Install dependencies
npm install
# 3. Create a .env file and add the following:
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
Note: Replace
your_spotify_client_idandyour_spotify_client_secretwith your Spotify Developer app credentials. The redirect URI must match the one set in your Spotify app settings.
# 4. Build
npm run build
# 5. Run the server
npm start
This will open a browser for Spotify authentication and start the server using stdio transport.
🔧 Tools
1. search_tracks
- Description: Search for tracks on Spotify based on a query string.
- Input Schema:
query(string, required): Search term (e.g., artist name, song title).
- Output: JSON array of up to 5 track objects with
name,artist,album,release_date,popularity,id, anduri. - Example:
{
"name": "search_tracks",
"arguments": {"query": "The Beatles"}
}
2. get_playback_state
- Description: Retrieve the current playback state of the user's Spotify account.
- Input Schema: None
- Output: JSON object with current track info, playback status, and device details, or "No active playback" if nothing is playing.
- Example:
{
"name": "get_playback_state",
"arguments": {}
}
3. play_track
- Description: Play a specific track using its Spotify URI.
- Input Schema:
uri(string, required): Spotify track URI (e.g.,spotify:track:xxx).
- Output: JSON confirmation with
statusanduri. - Example:
{
"name": "play_track",
"arguments": {"uri": "spotify:track:7KXjTSCq5nL1LoYtL7XAwS"}
}
4. get_user_playlists
- Description: Fetch the user's playlists from Spotify.
- Input Schema:
limit(number, optional): Maximum number of playlists to return (default: 20).
- Output: JSON array of playlist objects with
name,id,track_count,uri, andpublicstatus. - Example:
{
"name": "get_user_playlists",
"arguments": {"limit": 10}
}
5. pause_playback
- Description: Pause the current playback on the user's active Spotify device.
- Input Schema: None
- Output: JSON confirmation with "Playback paused" status.
- Example:
{
"name": "pause_playback",
"arguments": {}
}
🌐 Use Cases
-
Music Discovery Bot:
- Use
search_tracksandplay_trackto implement mood-based music chatbots.
- Use
-
Playlist Management Tool:
- Use
get_user_playlistsandsearch_tracksto preview and organize playlists.
- Use
-
Playback Control Automation:
- Automate playback actions using
get_playback_state,play_track, andpause_playback.
- Automate playback actions using
-
Spotify Dashboard:
- Build a desktop widget using
get_playback_state,get_user_playlists,pause_playback, andplay_track.
- Build a desktop widget using
-
Learning Spotify API:
- Experiment with all tools to learn how the Spotify Web API works.
🔐 Authentication Details
- On first run, the server opens a browser for Spotify OAuth authentication.
- Receives code via
http://localhost:8888/callback. - Exchanges the code for access and refresh tokens.
- Automatically refreshes tokens within 5 minutes of expiration.
⏱ Rate Limiting
- Handles Spotify API rate limits with retry strategies:
- 10-second cooldown after each request.
- 1-minute wait if a 429 Too Many Requests error occurs.
📊 Dependencies
npm install dotenv spotify-web-api-node @modelcontextprotocol/sdk open
dotenv: Loads environment variables from.env.spotify-web-api-node: Spotify API client.@modelcontextprotocol/sdk: Implements the MCP server.http,url: Node.js built-ins for OAuth redirect server.open: Opens default browser for authentication.
📁 Development Info
- Entry Point:
index.js - Language: JavaScript (Node.js with ES modules)
- Run Command:
node index.js - Debugging: Check console logs for MCP or authentication errors.
⚠️ Limitations
- Spotify Premium is required for playback control.
- Supports only stdio transport (no HTTP, WebSocket, etc.).
search_tracksreturns max 5 results.- Assumes a single active device for playback.
🚀 Contributing
Feel free to open issues or submit pull requests to:
- Add new tools
- Enhance existing functionality
- Improve documentation
✍️ License
MIT License — free to use, modify, and distribute for personal or commercial use.
❤️ Footer
Built with ❤️ by Rakshitha C Devadiga on March 17, 2025