Cognitive-Stack/spotify-mcp-server

Spotify MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless integration with Spotify's Web API. This server enables AI assistants and applications to interact with Spotify for music playback control, playlist management, search functionality, and more.

Features

🎵 Playback Control

• Get current track information
• Start/pause/resume playback
• Skip tracks (single or multiple)
• Control playback with Spotify URIs

🔍 Search & Discovery

• Search for tracks, albums, artists, and playlists
• Get detailed information about any Spotify item
• Browse user's music library

📝 Playlist Management

• Create new playlists
• Add/remove tracks from playlists
• Modify playlist details (name, description)
• Get playlist contents

🎼 Queue Management

• Add tracks to playback queue
• View current queue

👤 User Data

• Access user's playlists
• Get detailed track/album/artist information

Prerequisites

• Python 3.12 or higher
• Spotify Premium account (required for playback control)
• Spotify Developer Application credentials

Quick Start

1. Spotify Developer Setup

1. Go to the Spotify Developer Dashboard
2. Create a new application
3. Note your Client ID and Client Secret
4. Add http://127.0.0.1:8080/callback to your app's redirect URIs

2. Installation

Using Poetry (Recommended)

# Clone the repository
git clone https://github.com/Cognitive-Stack/spotify-mcp-server.git
cd spotify-mcp-server

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

Using Docker

# Clone the repository
git clone https://github.com/Cognitive-Stack/spotify-mcp-server.git
cd spotify-mcp-server

# Create environment file
cp .env.example .env
# Edit .env with your Spotify credentials

# Start with Docker Compose
docker-compose up -d

3. Configuration

Create a .env file in the project root:

# Spotify API Credentials (Required)
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8080/callback

# Server Configuration
ENVIRONMENT=development
LOG_LEVEL=INFO
SERVER_HOST=127.0.0.1
SERVER_PORT=8081

# Optional Settings
AUTH_TIMEOUT=120
TOKEN_CACHE_PATH=./cache/.cache

4. Running the Server

Development Mode

# Using Poetry
poetry run python -m spotify_mcp

# Or with Python directly
python -m spotify_mcp

Production Mode (Docker)

docker-compose up -d

The server will be available at:

• MCP Endpoint: http://localhost:8081/mcp
• OAuth Callback: http://localhost:8080/callback

MCP Client Configuration

To use this server with an MCP-compatible client, add it to your configuration:

Claude Desktop

Add to your mcp.json configuration file:

{
  "servers": {
    "spotify-mcp": {
      "url": "http://localhost:8081/mcp",
      "type": "http"
    }
  }
}

VS Code with MCP Extension

{
  "servers": {
    "spotify-mcp": {
      "url": "localhost:8081/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

Authentication

The server uses Spotify's OAuth 2.0 flow for authentication:

1. On first use, the server will prompt you to authenticate
2. A browser window will open for Spotify login
3. After authorization, you'll be redirected to the callback URL
4. The server will store refresh tokens for subsequent use

Note: Tokens are automatically refreshed as needed.

Available Tools

Playback Control

playback_control

Manage music playback with various actions.

Parameters:

• action (required): Action to perform (get, start, pause, skip)
• spotify_uri (optional): Spotify URI for the start action
• num_skips (optional): Number of tracks to skip (1-10, default: 1)

Examples:

# Get current track
playback_control(action="get")

# Start playback
playback_control(action="start")

# Play specific track
playback_control(action="start", spotify_uri="spotify:track:4iV5W9uYEdYUVa79Axb7Rh")

# Pause playback
playback_control(action="pause")

# Skip 2 tracks
playback_control(action="skip", num_skips=2)

Search & Discovery

search_spotify

Search for music content on Spotify.

Parameters:

• query (required): Search query
• qtype (optional): Type of content (track, album, artist, playlist, or comma-separated combination)
• limit (optional): Number of results (1-50, default: 10)

Examples:

# Search for tracks
search_spotify(query="Bohemian Rhapsody", qtype="track", limit=5)

# Search multiple types
search_spotify(query="Queen", qtype="artist,album", limit=10)

get_item_info

Get detailed information about a specific Spotify item.

Parameters:

• item_uri (required): Spotify URI of the item

Examples:

# Get track info
get_item_info(item_uri="spotify:track:4iV5W9uYEdYUVa79Axb7Rh")

# Get artist info (includes albums and top tracks)
get_item_info(item_uri="spotify:artist:1dfeR4HaWDbWqFHLkxsg1d")

Playlist Management

get_user_playlists

Get the current user's playlists.

get_user_playlists()

create_playlist

Create a new playlist.

Parameters:

• name (required): Playlist name
• description (optional): Playlist description
• public (optional): Whether playlist is public (default: true)

Examples:

# Create basic playlist
create_playlist(name="My Rock Playlist")

# Create detailed playlist
create_playlist(
    name="Chill Vibes 2025", 
    description="Relaxing music for work and study",
    public=False
)

get_playlist_tracks

Get tracks from a specific playlist.

Parameters:

• playlist_id (required): Spotify playlist ID

get_playlist_tracks(playlist_id="37i9dQZF1DXcBWIGoYBM5M")

add_tracks_to_playlist

Add tracks to a playlist.

Parameters:

• playlist_id (required): Spotify playlist ID
• track_ids (required): List of track IDs

add_tracks_to_playlist(
    playlist_id="37i9dQZF1DXcBWIGoYBM5M",
    track_ids=["4iV5W9uYEdYUVa79Axb7Rh", "1s6uxKAVWCaGKdkCaAFf9S"]
)

remove_tracks_from_playlist

Remove tracks from a playlist.

Parameters:

• playlist_id (required): Spotify playlist ID
• track_ids (required): List of track IDs

remove_tracks_from_playlist(
    playlist_id="37i9dQZF1DXcBWIGoYBM5M",
    track_ids=["4iV5W9uYEdYUVa79Axb7Rh"]
)

change_playlist_details

Modify playlist information.

Parameters:

• playlist_id (required): Spotify playlist ID
• name (optional): New playlist name
• description (optional): New playlist description

change_playlist_details(
    playlist_id="37i9dQZF1DXcBWIGoYBM5M",
    name="Updated Playlist Name",
    description="New description"
)

Queue Management

manage_queue

Manage the playback queue.

Parameters:

• action (required): Action to perform (add, get)
• track_id (optional): Track ID for add action

Examples:

# Get current queue
manage_queue(action="get")

# Add track to queue
manage_queue(action="add", track_id="4iV5W9uYEdYUVa79Axb7Rh")

Example Use Cases

Creating a Playlist with AI

# Create a new playlist
result = create_playlist(
    name="AI Generated Rock 2025",
    description="Best rock tracks curated by AI"
)

# Search for rock tracks
tracks = search_spotify(
    query="rock 2024 2025 alternative",
    qtype="track",
    limit=20
)

# Add tracks to playlist (extract IDs from search results)
track_ids = [track["id"] for track in tracks["tracks"][:10]]
add_tracks_to_playlist(playlist_id=result["id"], track_ids=track_ids)

Smart Playback Control

# Get current track info
current = playback_control(action="get")

# If nothing is playing, start a discovery playlist
if "No track playing" in current:
    playback_control(
        action="start",
        spotify_uri="spotify:playlist:37i9dQZF1DX0XUsuxWHRQd"
    )

Deployment

Production Deployment with Docker

1. Environment Setup:

   # Copy and configure environment
   cp .env.example .env
   # Edit .env with production values
   

2. Deploy:

   # Build and start services
   docker-compose up -d
   
   # Check logs
   docker-compose logs -f spotify-mcp
   

3. Health Check:

   curl http://localhost:8081/health
   

Environment Variables

Troubleshooting

Common Issues

1. Authentication Problems

• Ensure your Spotify app's redirect URI matches SPOTIFY_REDIRECT_URI
• Check that Client ID and Secret are correct
• Verify you have a Spotify Premium account

2. Server Won't Start

• Check that ports 8080 and 8081 are available
• Verify all required environment variables are set
• Check logs: docker-compose logs spotify-mcp

3. Playback Control Issues

• Spotify Premium is required for playback control
• Ensure Spotify is active on at least one device
• Check device availability with playback_control(action="get")

Logs

View server logs:

# Docker
docker-compose logs -f spotify-mcp

# Local development
tail -f logs/spotify-mcp-errors.log

Reset Authentication

If you encounter persistent auth issues:

# Remove cached tokens
rm -f cache/.cache

# Restart server
docker-compose restart spotify-mcp

Development

Local Development Setup

# Clone and setup
git clone https://github.com/Cognitive-Stack/spotify-mcp-server.git
cd spotify-mcp-server

# Install dependencies
poetry install

# Setup pre-commit hooks
poetry run pre-commit install

# Run tests
poetry run pytest

# Start development server
poetry run python -m spotify_mcp

Project Structure

spotify-mcp-server/
├── spotify_mcp/           # Main package
│   ├── __init__.py
│   ├── server.py          # FastMCP server and tools
│   ├── spotify_api.py     # Spotify API client
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   ├── logging_config.py  # Logging setup
│   └── oauth_callback.py  # OAuth handler
├── docker-compose.yml     # Docker deployment
├── Dockerfile            # Container definition
├── pyproject.toml        # Python dependencies
├── .env.example          # Environment template
└── README.md             # This file

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This README and inline code documentation

Acknowledgments

• Spotify Web API for music data
• FastMCP for the MCP server framework
• Spotipy for Spotify API integration