Spotify Mcp Server

Spotipy MCP Server

[](https://github.com/jadilson12/spotify-mcp-server/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://github.com/jadilson12/spotify-mcp-server/actions)

MCP (Model Context Protocol) Server with Spotipy integration for music control via Spotify.

🚀 Features

• ✅ Playback control (play, pause, next, previous)
• ✅ Volume adjustment
• ✅ Music search
• ✅ Get current track
• ✅ Playlist management
• ✅ Complete REST API
• ✅ Automatic documentation (Swagger)
• ✅ Complete MCP integration with tools and resources

📋 Prerequisites

• Python 3.12+
• Spotify Developer account
• Registered application in Spotify Developer Dashboard

🛠️ Installation

1. Clone the repository:

git clone https://github.com/jadilson12/spotify-mcp-server
cd spotify-mcp-server

1. Install dependencies:

make install

1. Configure environment variables:

cp env.example .env

Edit the .env file with your Spotify credentials:

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

🎵 Spotify Configuration

📋 Step-by-Step Tutorial: Getting Spotify Credentials

Step 1: Access Spotify Developer Dashboard

1. Go to Spotify Developer Dashboard
2. Log in with your Spotify account (or create one if you don't have it)

Step 2: Create a New Application

1. Click "Create App" button
2. Fill in the application details:

• App name: Spotify MCP Server (or any name you prefer)
• App description: MCP Server for Spotify music control
• Website: http://localhost:8000 (optional)
• Redirect URI: http://localhost:8888/callback
• API/SDKs: Select "Web API"

1. Click "Save"

Step 3: Get Your Credentials

1. After creating the app, you'll be redirected to your app dashboard
2. Copy the Client ID (visible on the main page)
3. Click "Show Client Secret" and copy the Client Secret
4. ⚠️ Keep these credentials secure! Never share them publicly.

Step 4: Configure Redirect URIs

1. In your app dashboard, go to "Edit Settings"
2. Under "Redirect URIs", add: http://localhost:8888/callback
3. Click "Add" and then "Save"

Step 5: Configure Required Scopes

1. In your app dashboard, go to "Edit Settings"
2. Under "User Management", you'll see the scopes section
3. Important: The following scopes will be requested during authentication:

• user-read-playback-state - Read playback state
• user-modify-playback-state - Control playback
• user-read-currently-playing - Current track
• playlist-read-private - Private playlists
• user-library-read - User library
• user-top-read - Top artists and tracks
• user-read-recently-played - Recently played tracks
• user-follow-read - Followed artists
• user-read-email - User email
• user-read-private - Private information

Step 6: Update Your .env File

1. Copy the env.example file to .env
2. Replace the placeholder values with your actual credentials:

SPOTIFY_CLIENT_ID=your_actual_client_id_here
SPOTIFY_CLIENT_SECRET=your_actual_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

Step 7: Test Your Configuration

1. Start the server: make dev
2. The first time you use the API, you'll be redirected to Spotify for authentication
3. Accept the permissions requested by Spotify
4. You should now be able to control your Spotify music!

🔐 Security Tips

• Never commit your .env file to version control
• Keep your credentials private and secure
• Use different apps for development and production
• Regularly rotate your client secret if needed

🚀 Usage

Start the server:

make dev

The server will be available at:

• API: http://localhost:8000
• Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

🛠️ Development Guide

🔄 Essential Commands

# Complete server restart
pkill -f "python.*mcp-server" && sleep 2 && make dev

# Kill MCP ports (REQUIRED before run-inspector)
lsof -ti:6274 | xargs kill -9 && lsof -ti:6277 | xargs kill -9

# Check ports in use
lsof -i:6274 && lsof -i:6277

⚠️ IMPORTANT: Always Kill Ports!

BEFORE running make run-inspector, ALWAYS execute:

# Kill MCP ports (REQUIRED)
lsof -ti:6274 | xargs kill -9 && lsof -ti:6277 | xargs kill -9

Why is this necessary?

• MCP Inspector uses ports 6274 (UI) and 6277 (Proxy)
• If ports are occupied, Inspector cannot start
• Previous processes may have left ports in use

🎯 Development Workflow

1. After Modifying Code:

pkill -f "python.*mcp-server" && sleep 2 && make dev

1. To Test with MCP Inspector:

lsof -ti:6274 | xargs kill -9 && lsof -ti:6277 | xargs kill -9
make run-inspector

Available commands:

make dev              # Start development server
make install          # Install dependencies
make clean            # Clean temporary files
make test             # Run tests
make lint             # Check code quality
make format           # Format code
make run-inspector    # Run MCP Inspector
make help             # Show help

🎵 MCP Features

Available Tools:

• play_music - Play music
• search_tracks - Search tracks
• get_current_track - Current track
• get_playlists - List playlists
• get_recommendations - Recommendations
• get_user_profile - User profile
• get_devices - Available devices
• get_queue - Playback queue
• get_genres - Music genres
• get_audio_features - Audio characteristics

Available Resources:

• spotify://playback/current - Current playback
• spotify://playlists - User playlists
• spotify://devices - Devices
• spotify://genres - Genres
• spotify://profile - User profile
• spotify://playback/queue - Playback queue

Resource Templates:

• spotify://playlist/{playlist_id} - Specific playlist
• spotify://track/{track_id} - Specific track
• spotify://artist/{artist_id} - Specific artist
• spotify://album/{album_id} - Specific album
• spotify://search/{query} - Search results

📚 API Endpoints

Authentication

• POST /auth - Authenticate with Spotify
• POST /auth/reauth - Re-authenticate with configured credentials

Playback

• GET /current-track - Get current track
• POST /play - Play music
• POST /pause - Pause music
• POST /next - Next track
• POST /previous - Previous track
• POST /volume/{volume} - Adjust volume (0-100)
• POST /seek/{position_ms} - Seek to specific position
• POST /shuffle - Toggle shuffle mode
• POST /repeat - Toggle repeat mode

Playlists and Albums

• GET /playlists - Get user playlists
• GET /playlist/{playlist_id} - Get playlist tracks
• GET /albums - Get user saved albums
• GET /tracks - Get user saved tracks

Artists and Top Tracks

• GET /artists - Get user favorite artists
• GET /tracks/top - Get most played tracks

Playback Queue

• GET /queue - Get current playback queue
• POST /queue/add - Add track to queue

Devices

• GET /devices - Get available devices
• POST /devices/{device_id}/transfer - Transfer playback

Search and Recommendations

• GET /search/{query} - Search tracks
• GET /recommendations - Get personalized recommendations
• GET /genres - Get available music genres

User and Analysis

• GET /user/profile - Get user profile
• GET /audio-features/{track_id} - Get audio features

System

• GET / - Server status
• GET /health - Health check

🔧 Usage Examples

Play a specific track:

curl -X POST "http://localhost:8000/play" \
  -H "Content-Type: application/json" \
  -d '{"track_uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh"}'

Search tracks:

curl "http://localhost:8000/search/bohemian%20rhapsody?limit=5"

Adjust volume:

curl -X POST "http://localhost:8000/volume/50"

Get current track:

curl "http://localhost:8000/current-track"

Get user playlists:

curl "http://localhost:8000/playlists"

Get tracks from a specific playlist:

curl "http://localhost:8000/playlist/37i9dQZF1DXcBWIGoYBM5M"

Get saved tracks:

curl "http://localhost:8000/tracks"

Get favorite artists:

curl "http://localhost:8000/artists"

Get recommendations based on artists:

curl "http://localhost:8000/recommendations?seed_artists=4gzpq5DPGxSnKTe4SA8HAU&limit=10"

Toggle shuffle:

curl -X POST "http://localhost:8000/shuffle"

Add track to queue:

curl -X POST "http://localhost:8000/queue/add?track_uri=spotify:track:4iV5W9uYEdYUVa79Axb7Rh"

Get available devices:

curl "http://localhost:8000/devices"

Seek to specific position (30 seconds):

curl -X POST "http://localhost:8000/seek/30000"

Re-authenticate with Spotify:

curl -X POST "http://localhost:8000/auth/reauth"

🚀 CI/CD Pipeline

📊 Pipeline Status

Our CI/CD pipeline ensures code quality and security:

• ✅ Tests: 60 tests passing on Python 3.12 & 3.13
• ✅ Linting: Code quality checks with flake8
• ✅ Formatting: Black and isort formatting validation
• ✅ Security: Secrets detection and .env file validation
• ✅ Build: Package building and artifact generation

🔄 Pipeline Jobs

| Job | Description | Status | | ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Test | Run all tests on Python 3.12 & 3.13 | | | Lint | Code quality and formatting checks | | | Security | Secrets detection and security validation | | | Build | Package building and distribution | |

🛡️ Security Checks

The pipeline includes comprehensive security validation:

• 🔍 TruffleHog: Advanced secret scanner for detecting credentials
• 🕵️ detect-secrets: Multi-pattern secret detection with baseline
• 🔐 Pattern Matching: Custom regex patterns for sensitive data
• 📁 File Validation: Checks for committed sensitive files (.env, .key, .pem)
• ⚙️ Gitignore Validation: Ensures sensitive file patterns are ignored
• 🌐 URL Scanning: Detects hardcoded cloud service URLs
• 📊 Security Reports: Generates detailed security scan artifacts

Protected Patterns:

• API keys and tokens
• Passwords and secrets
• Base64/Hex encoded strings
• AWS, Google, Azure credentials
• Private keys and certificates
• Spotify client credentials

📋 Local Pipeline Testing

Test the pipeline locally before pushing:

# Run all pipeline checks locally
make test-pytest    # Tests
make lint          # Linting
make format        # Formatting
make security      # Security checks

🔐 Security Commands

# Run security checks
make security       # Basic security validation

# Full security scan (requires tools)
pip install detect-secrets truffleHog3
detect-secrets scan --all-files
trufflehog3 --format json .

🧪 Tests

✅ 60 tests PASSING | ⏱️ ~0.38s | 🔧 100% Functional

🚀 Run Tests

# Run all tests (recommended)
make test-pytest

# Or use pytest directly
python -m pytest tests/ -v --tb=short --color=yes

📋 Test Coverage

🔧 MCP Tools Tests (36 tests)

• ✅ Playback control (play_music, pause_music, next_track, previous_track)
• ✅ Volume management (set_volume)
• ✅ Search and discovery (search_tracks, search_artists, search_albums, search_playlists)
• ✅ Playlists and albums (get_playlists, get_playlist_tracks, get_album_tracks)
• ✅ Profile and preferences (get_user_profile, get_top_tracks, get_top_artists)
• ✅ Personal library (get_saved_tracks, get_saved_albums, get_followed_artists)
• ✅ Devices and queue (get_devices, get_queue, add_to_queue)
• ✅ Recommendations (get_recommendations, get_genres, get_audio_features)
• ✅ Navigation (skip_to_next, skip_to_previous, seek_to_position)
• ✅ History (get_recently_played)
• ✅ Related artists (get_related_artists, get_artist_top_tracks, get_artist_albums)

💬 MCP Prompts Tests (6 tests)

• ✅ spotify_assistant - Intelligent music assistant
• ✅ spotify_usage_guide - Feature usage guide
• ✅ spotify_troubleshooting - Problem solving

📚 MCP Resources Tests (12 tests)

• ✅ spotify://playback/current - Current playback state
• ✅ spotify://playlists/user - User playlists
• ✅ spotify://devices/available - Available devices
• ✅ spotify://genres/available - Music genres
• ✅ spotify://user/profile - User profile
• ✅ spotify://playback/queue - Playback queue
• ✅ spotify://user/top-tracks - Top tracks
• ✅ spotify://user/top-artists - Top artists
• ✅ spotify://user/recently-played - Recently played
• ✅ spotify://user/saved-tracks - Saved tracks
• ✅ spotify://user/saved-albums - Saved albums
• ✅ spotify://user/followed-artists - Followed artists

🔧 Functionality Tests (3 tests)

• ✅ Correct tool structure
• ✅ Valid descriptions in all tools
• ✅ Error handling implemented

📊 Validation Tests (2 tests)

• ✅ Volume request validation
• ✅ Search request validation

🔗 Integration Test (1 test)

• ✅ Server completeness (tools, prompts, resources)

🎯 Available Test Commands

# Run all tests
make test-pytest           # Using pytest (recommended)

# Specific tests (future)
make test-tools            # Tools tests only
make test-prompts          # Prompts tests only
make test-resources        # Resources tests only
make test-integration      # Integration tests only
make test-coverage         # Check coverage

# Test with detailed output
python -m pytest tests/ -v -s --tb=long

📈 Latest Test Results

===================================== test session starts =====================================
collected 60 items

TestMCPServerBasics ✅ (4/4)
TestMCPTools ✅ (36/36)
TestMCPPrompts ✅ (6/6)
TestMCPResources ✅ (12/12)
TestToolFunctionality ✅ (2/2)
TestErrorHandling ✅ (1/1)
TestDataValidation ✅ (2/2)
TestIntegration ✅ (1/1)

===================================== 60 passed in 0.38s ======================================

🔍 Test Structure

tests/
├── test_main.py          # All MCP server tests
├── __init__.py           # Module initialization
└── README.md            # Test documentation

🧪 How to Add New Tests

1. For new tool:

@pytest.mark.asyncio
async def test_new_tool_exists(self):
    """Test if new tool exists"""
    tools = await app.get_tools()
    assert 'new_tool' in tools

1. For new resource:

@pytest.mark.asyncio
async def test_new_resource_exists(self):
    """Test if new resource exists"""
    resources = await app.get_resources()
    assert 'spotify://new/resource' in resources

⚠️ Important for Tests

• ALWAYS run tests after modifying code
• Use make test-pytest for fast and reliable execution
• Tests don't require real Spotify authentication
• Tests focus on structure and feature availability

🔍 Linting and Formatting

make lint    # Check code quality
make format  # Format code automatically

📝 Project Structure

mcp-server/
├── src/
│   ├── mcp-server.py    # Main MCP server
│   ├── service.py       # Spotify lo

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jadilson12](https://github.com/jadilson12)
- **Source:** [jadilson12/spotify-mcp-server](https://github.com/jadilson12/spotify-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.