spotify-mcp-server by oe-ai-experiments - MCP Server

Spotify MCP Server

A FastMCP server for interacting with Spotify Web API, enabling AI assistants to search tracks, manage playlists, and access music metadata through the Model Context Protocol (MCP).

Features

🎵 MCP Tools

search_tracks - Search for tracks with filtering and pagination
get_playlists - Get user's playlists with pagination
get_playlist - Get detailed playlist with tracks
create_playlist - Create new playlists with description/visibility
add_tracks_to_playlist - Add tracks to playlists with position control
remove_tracks_from_playlist - Remove tracks from playlists
get_track_details - Get detailed track info with audio features
get_album_details - Get album information with track listing
get_artist_details - Get artist information and metadata
get_cache_stats - Monitor cache performance and statistics
cleanup_cache - Remove expired cache entries
clear_user_cache - Clear cache for current user (by data type)

📚 MCP Resources

playlists://{path} - Access playlist data (e.g., playlists://user/all, playlists://user/{playlist_id})
tracks://{path} - Access track data (e.g., tracks://search/{query}, tracks://details/{track_id})
albums://{path} - Access album data (e.g., albums://details/{album_id})
artists://{path} - Access artist data (e.g., artists://details/{artist_id})

🔐 Authentication & Security

OAuth 2.0 Authorization Code flow with PKCE
Automatic token refresh with encrypted storage
Interactive CLI authentication flow
Secure credential management

⚡ High-Performance Caching

Hybrid SQLite + Memory Cache - Best of both worlds: persistence + speed
Intelligent TTL Management - Different cache lifetimes for different data types
Bulk Operations - Efficient batch processing with partial cache hits
User Isolation - Multi-user cache with proper data separation
Performance Gains: 1,500x+ speedup for cached operations
Cache Management Tools - Built-in MCP tools for monitoring and cleanup

🚀 Production Features

Comprehensive error handling with retry logic (3-15-45 seconds)
Rate limiting respect (100 requests/minute)
Structured logging with configurable levels
Configuration via JSON files or environment variables
136+ passing unit tests with 100% success rate

Prerequisites

Python 3.8+
Spotify Developer Account
- Create an app at Spotify Developer Dashboard
- Note your Client ID and Client Secret
- Add http://localhost:8888/callback as a redirect URI

Installation

Option 1: Install with uvx (Recommended)

Install directly using uvx for the best experience:

# Install from GitHub
uvx --from git+https://github.com/oe-ai-experiments/spotify-mcp-server.git spotify-mcp-server --setup-auth

# Or install from local directory
git clone https://github.com/oe-ai-experiments/spotify-mcp-server.git
cd spotify-mcp-server
uvx --from . spotify-mcp-server --setup-auth

Option 2: Development Installation

For development and testing:

git clone https://github.com/oe-ai-experiments/spotify-mcp-server.git
cd spotify-mcp-server

# Install in development mode
pip install -e ".[dev]"

# Or use uv for faster dependency management
uv pip install -e ".[dev]"

Configuration

Method 1: Configuration File

Create configuration file:

python -m spotify_mcp_server.main --create-config config.json

Edit config.json with your Spotify credentials:

{
  "spotify": {
    "client_id": "your_spotify_client_id_here",
    "client_secret": "your_spotify_client_secret_here",
    "redirect_uri": "http://localhost:8888/callback",
    "scopes": [
      "playlist-read-private",
      "playlist-modify-public", 
      "playlist-modify-private",
      "user-library-read",
      "user-read-private"
    ]
  },
  "server": {
    "host": "localhost",
    "port": 8000,
    "log_level": "INFO"
  },
  "api": {
    "rate_limit": 100,
    "retry_attempts": 3,
    "retry_delays": [3, 15, 45],
    "timeout": 30
  },
  "cache": {
    "enabled": true,
    "db_path": "spotify_cache.db",
    "memory_limit": 1000,
    "default_ttl_hours": 24,
    "audio_features_ttl_hours": 168,
    "playlist_ttl_hours": 1,
    "track_details_ttl_hours": 24,
    "cleanup_interval_hours": 24
  }
}

Method 2: Environment Variables

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REDIRECT_URI="http://localhost:8888/callback"

Usage

Running the Server

# With config file
python -m spotify_mcp_server.main --config config.json

# With environment variables
python -m spotify_mcp_server.main

# With uvx
uvx run spotify-mcp-server --config config.json

First-Time Authentication

Start the server - it will detect you need authentication
Follow the interactive prompts:
- Open the provided authorization URL in your browser
- Authorize the application in Spotify
- Copy the callback URL from your browser
- Paste it back in the terminal
Tokens are automatically saved and refreshed for future use

Using with MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client.

Cursor Integration

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "spotify": {
      "command": "/path/to/your/project/run-mcp-server.sh",
      "args": ["--config", "config.json"]
    }
  }
}

Direct uvx Integration

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oe-ai-experiments/spotify-mcp-server.git", "spotify-mcp-server", "--config", "/absolute/path/to/config.json"]
    }
  }
}

Example Usage

Search for Tracks

# Using MCP client
result = await client.call_tool("search_tracks", {
    "query": "bohemian rhapsody",
    "limit": 10,
    "market": "US"
})

Create and Manage Playlists

# Create playlist
playlist = await client.call_tool("create_playlist", {
    "name": "My AI Playlist",
    "description": "Created by AI assistant",
    "public": false
})

# Add tracks
await client.call_tool("add_tracks_to_playlist", {
    "playlist_id": playlist["id"],
    "track_uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh"]
})

Access Resources

# Get all playlists
playlists = await client.read_resource("playlists://user/all")

# Get track details
track_info = await client.read_resource("tracks://details/4iV5W9uYEdYUVa79Axb7Rh")

# Search results as resource
search_results = await client.read_resource("tracks://search/rock music")

Development

Running Tests

# Unit tests
python -m pytest tests/ -v

# Integration tests (requires Spotify credentials)
export SPOTIFY_CLIENT_ID="your_id"
export SPOTIFY_CLIENT_SECRET="your_secret"
python -m pytest tests/test_integration.py -v

# All tests with coverage
python -m pytest tests/ --cov=spotify_mcp_server --cov-report=html

Code Quality

# Linting
flake8 src/ tests/
mypy src/

# Formatting
black src/ tests/
isort src/ tests/

Configuration Reference

Spotify Configuration

client_id - Spotify application client ID
client_secret - Spotify application client secret
redirect_uri - OAuth callback URL (must match Spotify app settings)
scopes - List of Spotify API scopes to request

Server Configuration

host - Server bind address (default: "localhost")
port - Server port (default: 8000)
log_level - Logging level: DEBUG, INFO, WARNING, ERROR

API Configuration

rate_limit - Requests per minute (default: 100)
retry_attempts - Number of retry attempts (default: 3)
retry_delays - Delay between retries in seconds (default: [3, 15, 45])
timeout - Request timeout in seconds (default: 30)

Cache Configuration

enabled - Enable/disable caching (default: true)
db_path - SQLite database file path (default: "spotify_cache.db")
memory_limit - Maximum items in memory cache (default: 1000)
default_ttl_hours - Default cache lifetime in hours (default: 24)
audio_features_ttl_hours - Audio features cache lifetime (default: 168 = 1 week)
playlist_ttl_hours - Playlist cache lifetime (default: 1 hour)
track_details_ttl_hours - Track details cache lifetime (default: 24 hours)
cleanup_interval_hours - Automatic cleanup interval (default: 24 hours)

Cache Performance

The cache system provides dramatic performance improvements:

Single requests: 1,500x+ speedup (50ms → 0.03ms)
Bulk operations: 30,000x+ speedup (3s → 0.1ms)
Playlist analysis: 34,000x+ speedup (19s → 0.5ms)

Cache Management

Use the built-in MCP tools to manage cache:

# Get cache statistics
get_cache_stats

# Clean up expired entries
cleanup_cache

# Clear user cache (optional: specify data type)
clear_user_cache audio_features

Troubleshooting

Authentication Issues

Ensure redirect URI in config matches Spotify app settings exactly
Check that all required scopes are included
Verify client credentials are correct

Rate Limiting

Default limit is 100 requests/minute (Spotify's limit)
Server automatically handles rate limits with exponential backoff
Reduce rate_limit in config if needed

Token Issues

Tokens are stored in tokens.json (encrypted)
Delete tokens.json to force re-authentication
Check token expiration in logs

Network Issues

Server includes automatic retry logic with exponential backoff
Check firewall settings for localhost:8888 (OAuth callback)
Verify internet connectivity to Spotify API

Cache Issues

Cache not working: Check cache.enabled in config
Performance issues: Monitor cache hit rates with get_cache_stats
Disk space: Cache database grows over time, use cleanup_cache regularly
Memory usage: Reduce memory_limit if using too much RAM
Stale data: Lower TTL values for frequently changing data
Database errors: Delete spotify_cache.db to reset cache

License

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

Contributing

Fork the repository
Create a feature branch
Make your changes with tests
Run the test suite
Submit a pull request

Support

For issues and questions:

Check the troubleshooting section
Review server logs for detailed error messages
Open an issue with reproduction steps