fisknils/spotify-mcp-server

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

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Add http://127.0.0.1:3000/callback as a redirect URI
4. 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 query
• type (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 name
• description (string, optional): Playlist description
• public (boolean, optional): Whether playlist is public (default: false)

spotify_add_tracks_to_playlist

Add tracks to a playlist.

Parameters:

• playlist_id (string): Playlist ID
• track_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

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

2. Search for tracks:

Use spotify_search with query "Bohemian Rhapsody" and type "track"

3. Create a playlist:

Use spotify_create_playlist with name "My New Playlist"

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