Spotify MCP Server

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

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

⚙️ Configuration

Python Implementation

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

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:

📁 Project Structure

Python Implementation

Vercel Implementation

🔧 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)