spotify-mcp-server 0.1.5

Model Context Protocol server for Spotify integration

Spotify MCP Server

A Model Context Protocol (MCP) server that provides Spotify integration, allowing AI assistants and applications to interact with Spotify's music streaming service.

Features

Artist Tools

• Search Artists - Search for artists by name
• Get Artist - Get detailed information about a specific artist
• Get Artist Albums - Get all albums for an artist
• Get Artist Top Tracks - Get an artist's most popular tracks

Album Tools

• Get Album - Get detailed information about a specific album
• Get Album Tracks - Get all tracks from an album
• Get New Releases - Get new album releases

Playlist Tools

• Create Playlist - Create new playlists
• Add Tracks to Playlist - Add tracks to existing playlists
• Get User Playlists - Get current user's playlists

User Tools

• Get User Top Artists - Get user's most listened to artists
• Get User Top Tracks - Get user's most listened to tracks

Installation

For Claude Desktop Users (Recommended)

The easiest way to use this server with Claude Desktop is via PyPI:

1. Get your Spotify API credentials (see Spotify API Setup below)
2. Add to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "Spotify": {
      "command": "uvx",
      "args": ["spotify-mcp-server"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}

3. Restart Claude Desktop
4. On first use, authenticate with Spotify when prompted

Development Setup

Prerequisites

• Python 3.10+
• Spotify Developer Account
• MCP Client (like Claude Desktop, Cursor, etc.)

Setup

1. Install Dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

2. Spotify API Setup {#spotify-api-setup}

1. Go to Spotify Developer Dashboard
2. Create a new application
3. Add http://localhost:8888/callback to your app's Redirect URIs
4. Copy your Client ID and Client Secret

3. Environment Configuration

Create a .env file in the project root:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

4. Authentication

On first run, the server will open a browser window for Spotify authentication. Follow the OAuth flow to authorize the application.

Usage

Running the Server

# Development mode with inspector
mcp dev spotify_mcp_server.py

# Or run directly
python spotify_mcp_server.py

Available Tools

Artist Management

# Search for artists
search_artists(query="The Beatles", limit=10)

# Get artist details
get_artist(artist_id="3WrFJ7ztbogyGnTHbHJFl2")

# Get artist albums
get_artist_albums(artist_id="3WrFJ7ztbogyGnTHbHJFl2", include_groups="album,single")

# Get artist top tracks
get_artist_top_tracks(artist_id="3WrFJ7ztbogyGnTHbHJFl2", market="US")

Album Management

# Get album details
get_album(album_id="4aawyAB9vmqN3uQ7FjRGTy", market="US")

# Get album tracks
get_album_tracks(album_id="4aawyAB9vmqN3uQ7FjRGTy", limit=20)

# Get new releases
get_new_releases(country="US", limit=20)

Playlist Management

# Create a new playlist
create_playlist(name="My New Playlist", description="A great playlist", public=False)

# Add tracks to playlist
add_tracks_to_playlist(playlist_id="playlist_id", track_uris=["spotify:track:track_id"])

# Get user playlists
get_user_playlists()

User Data

# Get user's top artists
get_user_top_artists(time_range="medium_term", limit=20)

# Get user's top tracks
get_user_top_tracks(time_range="short_term", limit=10)

Project Structure

spotify-mcp/
├── spotify_mcp_server.py    # Main MCP server
├── mcp_tools/              # Tool modules
│   ├── __init__.py
│   ├── artist_tools.py     # Artist-related tools
│   ├── playlist_tools.py   # Playlist-related tools
│   ├── albums.py          # Album-related tools
│   └── user_tools.py      # User-related tools
├── .env                    # Environment variables
├── .spotify_cache         # Spotify OAuth cache
├── requirements.txt        # Python dependencies
└── README.md             # This file

API Reference

Artist Tools

search_artists

Search for artists on Spotify.

Parameters:

• query (str): Search query for artist name
• limit (int, optional): Maximum number of results (default: 10, max: 50)

Returns:

• List of artists with ID, name, popularity, followers, genres, and Spotify URL

get_artist

Get detailed information about an artist.

Parameters:

• artist_id (str): Spotify artist ID

Returns:

• Detailed artist information including images, genres, and popularity

get_artist_albums

Get albums for an artist.

Parameters:

• artist_id (str): Spotify artist ID
• include_groups (str, optional): Album types to include (default: "album,single")
• limit (int, optional): Maximum albums to return (default: 20, max: 50)

Returns:

• List of albums with details including release date, track count, and cover images

get_artist_top_tracks

Get top tracks for an artist.

Parameters:

• artist_id (str): Spotify artist ID
• market (str, optional): Market/country code (default: "US")

Returns:

• List of top tracks with popularity, duration, and album information

Album Tools

get_album

Get detailed information about an album.

Parameters:

• album_id (str): Spotify album ID
• market (str, optional): Market/country code (default: "US")

Returns:

• Detailed album information including artists, images, and genres

get_album_tracks

Get tracks from an album.

Parameters:

• album_id (str): Spotify album ID
• market (str, optional): Market/country code (default: "US")
• limit (int, optional): Maximum tracks to return (default: 20, max: 50)
• offset (int, optional): Starting index (default: 0)

Returns:

• List of tracks with track number, duration, and artist information

get_new_releases

Get new album releases.

Parameters:

• country (str, optional): Country code (default: "US")
• limit (int, optional): Maximum albums to return (default: 20, max: 50)
• offset (int, optional): Starting index (default: 0)

Returns:

• List of new release albums with artist and image information

Playlist Tools

create_playlist

Create a new Spotify playlist.

Parameters:

• name (str): Name of the playlist
• description (str, optional): Description of the playlist
• public (bool, optional): Whether the playlist is public (default: False)
• collaborative (bool, optional): Whether the playlist is collaborative (default: False)

Returns:

• Playlist information including ID, name, and Spotify URL

add_tracks_to_playlist

Add tracks to an existing playlist.

Parameters:

• playlist_id (str): Spotify playlist ID
• track_uris (List[str]): List of Spotify track URIs

Returns:

• Success status and number of tracks added

get_user_playlists

Get current user's playlists.

Parameters:

• None

Returns:

• List of user's playlists with details including track count and privacy settings

User Tools

get_user_top_artists

Get user's most listened to artists from Spotify.

Parameters:

• time_range (str, optional): Time period for top artists (default: "medium_term")
  • "short_term": Last 4 weeks
  • "medium_term": Last 6 months
  • "long_term": Several years
• limit (int, optional): Maximum number of artists to return (default: 20, max: 50)
• offset (int, optional): Index of the first artist to return (default: 0)

Returns:

• List of top artists with ID, name, popularity, followers, genres, and Spotify URL

get_user_top_tracks

Get user's most listened to tracks from Spotify.

Parameters:

• time_range (str, optional): Time period for top tracks (default: "medium_term")
  • "short_term": Last 4 weeks
  • "medium_term": Last 6 months
  • "long_term": Several years
• limit (int, optional): Maximum number of tracks to return (default: 20, max: 50)
• offset (int, optional): Index of the first track to return (default: 0)

Returns:

• List of top tracks with ID, name, album info, artists, popularity, duration, and Spotify URL

Development

Adding New Tools

1. Create a new function in the appropriate tool module (artist_tools.py, playlist_tools.py, albums.py, or user_tools.py)
2. Add the function to the __init__.py exports
3. Create a wrapper function in spotify_mcp_server.py
4. Copy the docstring and register the tool

Testing

# Run the server in development mode
mcp dev spotify_mcp_server.py

# The MCP Inspector will open at http://localhost:6274
# Use it to test your tools interactively

Troubleshooting

Authentication Issues

• Ensure your .env file has the correct Spotify credentials
• Check that your redirect URI matches exactly: http://localhost:8888/callback
• Clear the .spotify_cache file if you encounter token issues

API Rate Limits

• Spotify has rate limits on API calls
• The server includes error handling for rate limit responses
• Consider implementing caching for frequently accessed data