# 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
```bash
npm install
```
### 2. Create a Spotify App
1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/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**
```bash
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
```bash
npm run build
```
### 5. Configure Your MCP Client
Add the following to your MCP client settings (example for Claude Desktop):
```json
{
"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:
```bash
npm run dev
```
Build for production:
```bash
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
