Spotify MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless integration between applications and the Spotify API. This repository contains two implementations:

Python Implementation - Full-featured MCP server with 15 tools
Vercel Implementation - Lightweight JavaScript/Node.js server for cloud deployment

🐍 Python Implementation

A complete MCP server implementation that enables Poke by Interaction and other MCP-compatible applications to control Spotify playback, search for music, and manage playlists through natural language commands.

Features

🔐 Authentication: OAuth2 flow for secure Spotify API access
🎵 Playback Control: Play, pause, skip, seek, volume control
🔍 Search: Find tracks, albums, artists, and playlists
📋 Playlist Management: Create, modify, and manage playlists
👤 User Data: Access user's top tracks, recently played, and profile
📱 Device Management: Control playback on different devices
🎯 Smart Integration: Natural language commands for music control

Quick Start

1. Automated Setup

# Clone or download this project
cd poke

# Run the setup script
python setup.py

2. Manual Setup

Install Dependencies:
```
pip install -r requirements.txt
```
Spotify API Setup:
- Go to Spotify Developer Dashboard
- Create a new app
- Note your Client ID and Client Secret
- Set Redirect URI to http://localhost:8888/callback

Configuration:

# Copy the example environment file
cp .env.example .env

# Edit .env with your Spotify credentials
nano .env  # or use your preferred editor

Test the Connection:
```
python test_connection.py
```
Run the Server:
```
python main.py
```

MCP Tools Available (Python)

🎵 Playback Control

spotify_play - Start playback of a track or playlist
spotify_pause - Pause current playback
spotify_resume - Resume paused playback
spotify_skip_next - Skip to next track
spotify_skip_previous - Skip to previous track
spotify_set_volume - Set playback volume (0-100%)

🔍 Search & Discovery

spotify_search - Search for tracks, albums, artists, playlists
spotify_get_user_top_tracks - Get user's top tracks
spotify_get_recently_played - Get recently played tracks

📋 Playlist Management

spotify_get_user_playlists - Get user's playlists
spotify_create_playlist - Create a new playlist
spotify_add_to_playlist - Add tracks to a playlist

📱 Device & Status

spotify_get_current_track - Get currently playing track info
spotify_get_devices - Get available Spotify devices
spotify_get_user_profile - Get current user's profile

☁️ Vercel Implementation

A lightweight JavaScript/Node.js MCP server designed for cloud deployment on Vercel.

Environment Variables

Set these in your Vercel project:

SPOTIFY_CLIENT_ID - Your Spotify app client ID
SPOTIFY_CLIENT_SECRET - Your Spotify app client secret
SPOTIFY_REFRESH_TOKEN - (Optional) For user-specific operations

Endpoints

/api/test - Simple test endpoint
/api/index - MCP JSON-RPC endpoint for Poke integration

Usage in Poke

Server URL: https://your-vercel-url.vercel.app/api/index

🚀 Usage Examples

With Poke by Interaction

Once integrated, you can use natural language commands like:

"Play some jazz music"
"Search for Taylor Swift songs"
"Create a playlist called 'Workout Music'"
"Skip to the next track"
"Set volume to 50%"
"Show me my top tracks from this month"

Direct MCP Tool Calls

{
  "name": "spotify_search",
  "arguments": {
    "query": "jazz",
    "search_type": "track",
    "limit": 10
  }
}

⚙️ Configuration

Python Implementation

The server uses environment variables for configuration. Key settings in .env:

# Required: Spotify API credentials
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

# Optional: Server configuration
MCP_SERVER_NAME=spotify-mcp-server
MCP_SERVER_VERSION=1.0.0
CACHE_TTL=3600

Vercel Implementation

Set environment variables in your Vercel project dashboard.

🔗 Integration with Poke by Interaction

This MCP server is designed to work seamlessly with Poke by Interaction:

Choose your implementation (Python for local/self-hosted, Vercel for cloud)
Install and configure the MCP server following the setup instructions above
Configure Poke by Interaction to connect to this MCP server
Use natural language to control Spotify through Poke by Interaction

The server provides a comprehensive set of tools that enable Poke by Interaction to:

Understand music-related queries
Execute Spotify API operations
Provide rich responses with track information
Manage user's music library and playlists

🛠️ Troubleshooting

Common Issues

Authentication Errors:
- Verify your Spotify API credentials in .env (Python) or Vercel environment variables
- Ensure redirect URI matches your Spotify app settings
- Check that your Spotify app has the required scopes
No Devices Found:
- Make sure Spotify is open on at least one device
- Check that the device is active and connected to the internet
Permission Errors:
- Ensure your Spotify app has all required scopes enabled
- Re-authenticate if you've changed scopes

Debug Mode (Python)

Run with debug logging:

PYTHONPATH=. python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
import main
"

📁 Project Structure

Python Implementation

poke/
├── main.py              # Main entry point
├── mcp_server.py        # MCP server implementation
├── spotify_client.py    # Spotify API client
├── config.py           # Configuration management
├── test_connection.py  # Test script
├── setup.py           # Setup script
├── requirements.txt   # Python dependencies
├── .env.example      # Environment variables template
└── README.md         # This file

Vercel Implementation

api/
├── index.js           # Main MCP JSON-RPC endpoint
├── test.js           # Test endpoint
package.json          # Node.js dependencies
vercel.json          # Vercel configuration

🔧 Development

Adding New Tools (Python)

To add new Spotify functionality:

Add the tool definition in mcp_server.py handle_list_tools()
Implement the handler in mcp_server.py handle_call_tool()
Add the corresponding method in spotify_client.py
Update this README with the new tool documentation

Deployment (Vercel)

Fork this repository
Connect to Vercel
Set environment variables
Deploy

📄 License

This project is open source and available under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

🌟 Branches

main - Contains both Python and Vercel implementations
python-implementation - Python-only implementation
vercel - Vercel-only implementation (original)

Spotify MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless integration between applications and the Spotify API. This repository contains two implementations:

Python Implementation - Full-featured MCP server with 15 tools
Vercel Implementation - Lightweight JavaScript/Node.js server for cloud deployment

🐍 Python Implementation

Features

🔐 Authentication: OAuth2 flow for secure Spotify API access
🎵 Playback Control: Play, pause, skip, seek, volume control
🔍 Search: Find tracks, albums, artists, and playlists
📋 Playlist Management: Create, modify, and manage playlists
👤 User Data: Access user's top tracks, recently played, and profile
📱 Device Management: Control playback on different devices
🎯 Smart Integration: Natural language commands for music control

Quick Start

1. Automated Setup

# Clone or download this project
cd poke

# Run the setup script
python setup.py

2. Manual Setup

Install Dependencies:
```
pip install -r requirements.txt
```
Spotify API Setup:
- Go to Spotify Developer Dashboard
- Create a new app
- Note your Client ID and Client Secret
- Set Redirect URI to http://localhost:8888/callback

Configuration:

# Copy the example environment file
cp .env.example .env

# Edit .env with your Spotify credentials
nano .env  # or use your preferred editor

Test the Connection:
```
python test_connection.py
```
Run the Server:
```
python main.py
```

MCP Tools Available (Python)

🎵 Playback Control

spotify_play - Start playback of a track or playlist
spotify_pause - Pause current playback
spotify_resume - Resume paused playback
spotify_skip_next - Skip to next track
spotify_skip_previous - Skip to previous track
spotify_set_volume - Set playback volume (0-100%)

🔍 Search & Discovery

spotify_search - Search for tracks, albums, artists, playlists
spotify_get_user_top_tracks - Get user's top tracks
spotify_get_recently_played - Get recently played tracks

📋 Playlist Management

spotify_get_user_playlists - Get user's playlists
spotify_create_playlist - Create a new playlist
spotify_add_to_playlist - Add tracks to a playlist

📱 Device & Status

spotify_get_current_track - Get currently playing track info
spotify_get_devices - Get available Spotify devices
spotify_get_user_profile - Get current user's profile

☁️ Vercel Implementation

A lightweight JavaScript/Node.js MCP server designed for cloud deployment on Vercel.

Environment Variables

Set these in your Vercel project:

SPOTIFY_CLIENT_ID - Your Spotify app client ID
SPOTIFY_CLIENT_SECRET - Your Spotify app client secret
SPOTIFY_REFRESH_TOKEN - (Optional) For user-specific operations

Endpoints

/api/test - Simple test endpoint
/api/index - MCP JSON-RPC endpoint for Poke integration

Usage in Poke

Server URL: https://your-vercel-url.vercel.app/api/index

🚀 Usage Examples

With Poke by Interaction

Once integrated, you can use natural language commands like:

"Play some jazz music"
"Search for Taylor Swift songs"
"Create a playlist called 'Workout Music'"
"Skip to the next track"
"Set volume to 50%"
"Show me my top tracks from this month"

Direct MCP Tool Calls

{
  "name": "spotify_search",
  "arguments": {
    "query": "jazz",
    "search_type": "track",
    "limit": 10
  }
}

⚙️ Configuration

Python Implementation

The server uses environment variables for configuration. Key settings in .env:

# Required: Spotify API credentials
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

# Optional: Server configuration
MCP_SERVER_NAME=spotify-mcp-server
MCP_SERVER_VERSION=1.0.0
CACHE_TTL=3600

Vercel Implementation

Set environment variables in your Vercel project dashboard.

🔗 Integration with Poke by Interaction

This MCP server is designed to work seamlessly with Poke by Interaction:

Choose your implementation (Python for local/self-hosted, Vercel for cloud)
Install and configure the MCP server following the setup instructions above
Configure Poke by Interaction to connect to this MCP server
Use natural language to control Spotify through Poke by Interaction

The server provides a comprehensive set of tools that enable Poke by Interaction to:

Understand music-related queries
Execute Spotify API operations
Provide rich responses with track information
Manage user's music library and playlists

🛠️ Troubleshooting

Common Issues

Authentication Errors:
- Verify your Spotify API credentials in .env (Python) or Vercel environment variables
- Ensure redirect URI matches your Spotify app settings
- Check that your Spotify app has the required scopes
No Devices Found:
- Make sure Spotify is open on at least one device
- Check that the device is active and connected to the internet
Permission Errors:
- Ensure your Spotify app has all required scopes enabled
- Re-authenticate if you've changed scopes

Debug Mode (Python)

Run with debug logging:

PYTHONPATH=. python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
import main
"

📁 Project Structure

Python Implementation

poke/
├── main.py              # Main entry point
├── mcp_server.py        # MCP server implementation
├── spotify_client.py    # Spotify API client
├── config.py           # Configuration management
├── test_connection.py  # Test script
├── setup.py           # Setup script
├── requirements.txt   # Python dependencies
├── .env.example      # Environment variables template
└── README.md         # This file

Vercel Implementation

api/
├── index.js           # Main MCP JSON-RPC endpoint
├── test.js           # Test endpoint
package.json          # Node.js dependencies
vercel.json          # Vercel configuration

🔧 Development

Adding New Tools (Python)

To add new Spotify functionality:

Add the tool definition in mcp_server.py handle_list_tools()
Implement the handler in mcp_server.py handle_call_tool()
Add the corresponding method in spotify_client.py
Update this README with the new tool documentation

Deployment (Vercel)

Fork this repository
Connect to Vercel
Set environment variables
Deploy

📄 License

This project is open source and available under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

🌟 Branches

main - Contains both Python and Vercel implementations
python-implementation - Python-only implementation
vercel - Vercel-only implementation (original)