Provides comprehensive Spotify API integration with tools for playback control (play, pause, skip, volume), music search and discovery, playlist management, device control, and access to user data like top tracks and listening history.
Offers a lightweight cloud deployment option for the MCP server as a JavaScript/Node.js implementation that can be hosted on Vercel's platform.
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
2. Manual Setup
Install Dependencies:
pip install -r requirements.txtSpotify API Setup:
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 editorTest the Connection:
python test_connection.pyRun the Server:
python main.py
MCP Tools Available (Python)
šµ Playback Control
spotify_play
- Start playback of a track or playlistspotify_pause
- Pause current playbackspotify_resume
- Resume paused playbackspotify_skip_next
- Skip to next trackspotify_skip_previous
- Skip to previous trackspotify_set_volume
- Set playback volume (0-100%)
š Search & Discovery
spotify_search
- Search for tracks, albums, artists, playlistsspotify_get_user_top_tracks
- Get user's top tracksspotify_get_recently_played
- Get recently played tracks
š Playlist Management
spotify_get_user_playlists
- Get user's playlistsspotify_create_playlist
- Create a new playlistspotify_add_to_playlist
- Add tracks to a playlist
š± Device & Status
spotify_get_current_track
- Get currently playing track infospotify_get_devices
- Get available Spotify devicesspotify_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 IDSPOTIFY_CLIENT_SECRET
- Your Spotify app client secretSPOTIFY_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:
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 variablesEnsure 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:
š Project Structure
Python Implementation
Vercel Implementation
š§ 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 implementationspython-implementation
- Python-only implementationvercel
- Vercel-only implementation (original)
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables control of Spotify playback, music search, and playlist management through natural language commands. Available in both Python and Vercel implementations with comprehensive OAuth2 authentication and device management.