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:

1. Python Implementation - Full-featured MCP server with 15 tools
2. 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

1. Install Dependencies:

   pip install -r requirements.txt
   

2. 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

3. Configuration:

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env with your Spotify credentials
   nano .env  # or use your preferred editor
   

4. Test the Connection:

   python test_connection.py
   

5. 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:

1. Choose your implementation (Python for local/self-hosted, Vercel for cloud)
2. Install and configure the MCP server following the setup instructions above
3. Configure Poke by Interaction to connect to this MCP server
4. 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

1. 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

2. No Devices Found:

   • Make sure Spotify is open on at least one device
   • Check that the device is active and connected to the internet

3. 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:

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

Deployment (Vercel)

1. Fork this repository
2. Connect to Vercel
3. Set environment variables
4. 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)