Spotify API MCP
A Model Context Protocol (MCP) server that enables MCP-compatible applications (like Claude Desktop, IDEs, and other AI tools) to interact with the Spotify API, including authenticated endpoints for playlist management.
Features
- Search: Search for tracks, artists, albums, and playlists
- Authentication: OAuth 2.0 flow with PKCE for secure authentication
- User Profile: Get current user information
- Playlist Management: Create playlists and add tracks
- Token Management: Automatic token refresh
Setup
1. Install Dependencies
npm install
2. Create a Spotify App
- Go to Spotify Developer Dashboard
- Create a new app
- Add
http://127.0.0.1:3000/callbackas a redirect URI - Note your Client ID and Client Secret
3. Set Up Authentication (Optional)
You can provide your Spotify credentials in several ways:
Option A: Environment Variables
export SPOTIFY_CLIENT_ID="your_client_id_here"
export SPOTIFY_CLIENT_SECRET="your_client_secret_here"
Option B: Configuration File
Create a .env file in the project root:
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
Option C: Manual Authentication
If no credentials are pre-configured, you can use the spotify_authenticate tool to provide them when needed.
4. Build the Project
npm run build
5. Configure Your MCP Client
Add the following to your MCP client settings (example for Claude Desktop):
{
"mcpServers": {
"spotify": {
"command": "node",
"args": ["/path/to/spotify-api-mcp/dist/index.js"]
}
}
}
For other MCP clients, consult your client's documentation for the appropriate configuration format.
Note for Claude Desktop users: When you first try to use any Spotify functionality, Claude will automatically prompt you to authenticate by asking for your Spotify app's client ID and client secret. You don't need to provide these credentials in the configuration above.
Available Tools
spotify_authenticate
Authenticate with Spotify using OAuth 2.0. Required before using authenticated endpoints.
Parameters:
client_id(string, optional): Your Spotify app's client ID (can be set via environment variable)client_secret(string, optional): Your Spotify app's client secret (can be set via environment variable)
spotify_search
Search for content on Spotify.
Parameters:
query(string): Search querytype(string): Type of content (track,artist,album,playlist)limit(number, optional): Number of results (1-50, default: 10)
spotify_get_user_profile
Get the authenticated user's profile information.
spotify_create_playlist
Create a new playlist for the authenticated user.
Parameters:
name(string): Playlist namedescription(string, optional): Playlist descriptionpublic(boolean, optional): Whether playlist is public (default: false)
spotify_add_tracks_to_playlist
Add tracks to a playlist.
Parameters:
playlist_id(string): Playlist IDtrack_uris(array): Array of Spotify track URIs
spotify_get_user_playlists
Get the authenticated user's playlists.
Parameters:
limit(number, optional): Number of playlists to return (1-50, default: 20)
Usage Example
- First, authenticate with Spotify:
Use the spotify_authenticate tool with your client ID and secret
For Claude Desktop users: Simply ask Claude to search for music or create a playlist. Claude will automatically handle the authentication process and ask you for your Spotify credentials when needed.
- Search for tracks:
Use spotify_search with query "Bohemian Rhapsody" and type "track"
- Create a playlist:
Use spotify_create_playlist with name "My New Playlist"
- Add tracks to the playlist:
Use spotify_add_tracks_to_playlist with the playlist ID and track URIs from search results
Note: The exact syntax for using these tools depends on your MCP client. The examples above show the general approach.
Development
Run in development mode:
npm run dev
Build for production:
npm run build
Security Notes
- Client secrets are handled securely and not logged
- OAuth 2.0 with PKCE is used for authentication
- Tokens are automatically refreshed when needed
- Local server runs temporarily only during authentication
License
MIT