# Spotify MCP Server
A Model Context Protocol (MCP) server that provides Spotify integration, allowing AI assistants and applications to interact with Spotify's music streaming service.
## Features
### Artist Tools
- **Search Artists** - Search for artists by name
- **Get Artist** - Get detailed information about a specific artist
- **Get Artist Albums** - Get all albums for an artist
- **Get Artist Top Tracks** - Get an artist's most popular tracks
### Album Tools
- **Get Album** - Get detailed information about a specific album
- **Get Album Tracks** - Get all tracks from an album
- **Get New Releases** - Get new album releases
### Playlist Tools
- **Create Playlist** - Create new playlists
- **Add Tracks to Playlist** - Add tracks to existing playlists
- **Get User Playlists** - Get current user's playlists
### User Tools
- **Get User Top Artists** - Get user's most listened to artists
- **Get User Top Tracks** - Get user's most listened to tracks
## Installation
### For Claude Desktop Users (Recommended)
The easiest way to use this server with Claude Desktop is via PyPI:
1. Get your Spotify API credentials (see [Spotify API Setup](#spotify-api-setup) below)
2. Add to your Claude Desktop config at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"Spotify": {
"command": "uvx",
"args": ["spotify-mcp-server"],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id_here",
"SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
"SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
}
}
}
}
```
3. Restart Claude Desktop
4. On first use, authenticate with Spotify when prompted
## Development Setup
### Prerequisites
- Python 3.10+
- Spotify Developer Account
- MCP Client (like Claude Desktop, Cursor, etc.)
## Setup
### 1. Install Dependencies
```bash
# Using uv (recommended)
uv sync
# Or using pip
pip install -r requirements.txt
```
### 2. Spotify API Setup {#spotify-api-setup}
1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. Create a new application
3. Add `http://localhost:8888/callback` to your app's Redirect URIs
4. Copy your Client ID and Client Secret
### 3. Environment Configuration
Create a `.env` file in the project root:
```env
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
```
### 4. Authentication
On first run, the server will open a browser window for Spotify authentication. Follow the OAuth flow to authorize the application.
## Usage
### Running the Server
```bash
# Development mode with inspector
mcp dev spotify_mcp_server.py
# Or run directly
python spotify_mcp_server.py
```
### Available Tools
#### Artist Management
```python
# Search for artists
search_artists(query="The Beatles", limit=10)
# Get artist details
get_artist(artist_id="3WrFJ7ztbogyGnTHbHJFl2")
# Get artist albums
get_artist_albums(artist_id="3WrFJ7ztbogyGnTHbHJFl2", include_groups="album,single")
# Get artist top tracks
get_artist_top_tracks(artist_id="3WrFJ7ztbogyGnTHbHJFl2", market="US")
```
#### Album Management
```python
# Get album details
get_album(album_id="4aawyAB9vmqN3uQ7FjRGTy", market="US")
# Get album tracks
get_album_tracks(album_id="4aawyAB9vmqN3uQ7FjRGTy", limit=20)
# Get new releases
get_new_releases(country="US", limit=20)
```
#### Playlist Management
```python
# Create a new playlist
create_playlist(name="My New Playlist", description="A great playlist", public=False)
# Add tracks to playlist
add_tracks_to_playlist(playlist_id="playlist_id", track_uris=["spotify:track:track_id"])
# Get user playlists
get_user_playlists()
```
#### User Data
```python
# Get user's top artists
get_user_top_artists(time_range="medium_term", limit=20)
# Get user's top tracks
get_user_top_tracks(time_range="short_term", limit=10)
```
## Project Structure
```
spotify-mcp/
├── spotify_mcp_server.py # Main MCP server
├── mcp_tools/ # Tool modules
│ ├── __init__.py
│ ├── artist_tools.py # Artist-related tools
│ ├── playlist_tools.py # Playlist-related tools
│ ├── albums.py # Album-related tools
│ └── user_tools.py # User-related tools
├── .env # Environment variables
├── .spotify_cache # Spotify OAuth cache
├── requirements.txt # Python dependencies
└── README.md # This file
```
## API Reference
### Artist Tools
#### `search_artists`
Search for artists on Spotify.
**Parameters:**
- `query` (str): Search query for artist name
- `limit` (int, optional): Maximum number of results (default: 10, max: 50)
**Returns:**
- List of artists with ID, name, popularity, followers, genres, and Spotify URL
#### `get_artist`
Get detailed information about an artist.
**Parameters:**
- `artist_id` (str): Spotify artist ID
**Returns:**
- Detailed artist information including images, genres, and popularity
#### `get_artist_albums`
Get albums for an artist.
**Parameters:**
- `artist_id` (str): Spotify artist ID
- `include_groups` (str, optional): Album types to include (default: "album,single")
- `limit` (int, optional): Maximum albums to return (default: 20, max: 50)
**Returns:**
- List of albums with details including release date, track count, and cover images
#### `get_artist_top_tracks`
Get top tracks for an artist.
**Parameters:**
- `artist_id` (str): Spotify artist ID
- `market` (str, optional): Market/country code (default: "US")
**Returns:**
- List of top tracks with popularity, duration, and album information
### Album Tools
#### `get_album`
Get detailed information about an album.
**Parameters:**
- `album_id` (str): Spotify album ID
- `market` (str, optional): Market/country code (default: "US")
**Returns:**
- Detailed album information including artists, images, and genres
#### `get_album_tracks`
Get tracks from an album.
**Parameters:**
- `album_id` (str): Spotify album ID
- `market` (str, optional): Market/country code (default: "US")
- `limit` (int, optional): Maximum tracks to return (default: 20, max: 50)
- `offset` (int, optional): Starting index (default: 0)
**Returns:**
- List of tracks with track number, duration, and artist information
#### `get_new_releases`
Get new album releases.
**Parameters:**
- `country` (str, optional): Country code (default: "US")
- `limit` (int, optional): Maximum albums to return (default: 20, max: 50)
- `offset` (int, optional): Starting index (default: 0)
**Returns:**
- List of new release albums with artist and image information
### Playlist Tools
#### `create_playlist`
Create a new Spotify playlist.
**Parameters:**
- `name` (str): Name of the playlist
- `description` (str, optional): Description of the playlist
- `public` (bool, optional): Whether the playlist is public (default: False)
- `collaborative` (bool, optional): Whether the playlist is collaborative (default: False)
**Returns:**
- Playlist information including ID, name, and Spotify URL
#### `add_tracks_to_playlist`
Add tracks to an existing playlist.
**Parameters:**
- `playlist_id` (str): Spotify playlist ID
- `track_uris` (List[str]): List of Spotify track URIs
**Returns:**
- Success status and number of tracks added
#### `get_user_playlists`
Get current user's playlists.
**Parameters:**
- None
**Returns:**
- List of user's playlists with details including track count and privacy settings
### User Tools
#### `get_user_top_artists`
Get user's most listened to artists from Spotify.
**Parameters:**
- `time_range` (str, optional): Time period for top artists (default: "medium_term")
- `"short_term"`: Last 4 weeks
- `"medium_term"`: Last 6 months
- `"long_term"`: Several years
- `limit` (int, optional): Maximum number of artists to return (default: 20, max: 50)
- `offset` (int, optional): Index of the first artist to return (default: 0)
**Returns:**
- List of top artists with ID, name, popularity, followers, genres, and Spotify URL
#### `get_user_top_tracks`
Get user's most listened to tracks from Spotify.
**Parameters:**
- `time_range` (str, optional): Time period for top tracks (default: "medium_term")
- `"short_term"`: Last 4 weeks
- `"medium_term"`: Last 6 months
- `"long_term"`: Several years
- `limit` (int, optional): Maximum number of tracks to return (default: 20, max: 50)
- `offset` (int, optional): Index of the first track to return (default: 0)
**Returns:**
- List of top tracks with ID, name, album info, artists, popularity, duration, and Spotify URL
## Development
### Adding New Tools
1. Create a new function in the appropriate tool module (`artist_tools.py`, `playlist_tools.py`, `albums.py`, or `user_tools.py`)
2. Add the function to the `__init__.py` exports
3. Create a wrapper function in `spotify_mcp_server.py`
4. Copy the docstring and register the tool
### Testing
```bash
# Run the server in development mode
mcp dev spotify_mcp_server.py
# The MCP Inspector will open at http://localhost:6274
# Use it to test your tools interactively
```
## Troubleshooting
### Authentication Issues
- Ensure your `.env` file has the correct Spotify credentials
- Check that your redirect URI matches exactly: `http://localhost:8888/callback`
- Clear the `.spotify_cache` file if you encounter token issues
### API Rate Limits
- Spotify has rate limits on API calls
- The server includes error handling for rate limit responses
- Consider implementing caching for frequently accessed data
Raw data
{
"_id": null,
"home_page": null,
"name": "spotify-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, assistant, mcp, model-context-protocol, spotify",
"author": "Nir Levy",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/87/62/515393d6ec59704702b81f3b2e75bb15a56e0bb0e80ef0ad54d926f727e2/spotify_mcp_server-0.1.6.tar.gz",
"platform": null,
"description": "# Spotify MCP Server\n\nA Model Context Protocol (MCP) server that provides Spotify integration, allowing AI assistants and applications to interact with Spotify's music streaming service.\n\n## Features\n\n### Artist Tools\n\n- **Search Artists** - Search for artists by name\n- **Get Artist** - Get detailed information about a specific artist\n- **Get Artist Albums** - Get all albums for an artist\n- **Get Artist Top Tracks** - Get an artist's most popular tracks\n\n### Album Tools\n\n- **Get Album** - Get detailed information about a specific album\n- **Get Album Tracks** - Get all tracks from an album\n- **Get New Releases** - Get new album releases\n\n### Playlist Tools\n\n- **Create Playlist** - Create new playlists\n- **Add Tracks to Playlist** - Add tracks to existing playlists\n- **Get User Playlists** - Get current user's playlists\n\n### User Tools\n\n- **Get User Top Artists** - Get user's most listened to artists\n- **Get User Top Tracks** - Get user's most listened to tracks\n\n## Installation\n\n### For Claude Desktop Users (Recommended)\n\nThe easiest way to use this server with Claude Desktop is via PyPI:\n\n1. Get your Spotify API credentials (see [Spotify API Setup](#spotify-api-setup) below)\n2. Add to your Claude Desktop config at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n \"mcpServers\": {\n \"Spotify\": {\n \"command\": \"uvx\",\n \"args\": [\"spotify-mcp-server\"],\n \"env\": {\n \"SPOTIFY_CLIENT_ID\": \"your_client_id_here\",\n \"SPOTIFY_CLIENT_SECRET\": \"your_client_secret_here\",\n \"SPOTIFY_REDIRECT_URI\": \"http://127.0.0.1:8888/callback\"\n }\n }\n }\n}\n```\n\n3. Restart Claude Desktop\n4. On first use, authenticate with Spotify when prompted\n\n\n## Development Setup\n\n### Prerequisites\n\n- Python 3.10+\n- Spotify Developer Account\n- MCP Client (like Claude Desktop, Cursor, etc.)\n\n## Setup\n\n### 1. Install Dependencies\n\n```bash\n# Using uv (recommended)\nuv sync\n\n# Or using pip\npip install -r requirements.txt\n```\n\n### 2. Spotify API Setup {#spotify-api-setup}\n\n1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)\n2. Create a new application\n3. Add `http://localhost:8888/callback` to your app's Redirect URIs\n4. Copy your Client ID and Client Secret\n\n### 3. Environment Configuration\n\nCreate a `.env` file in the project root:\n\n```env\nSPOTIFY_CLIENT_ID=your_client_id_here\nSPOTIFY_CLIENT_SECRET=your_client_secret_here\nSPOTIFY_REDIRECT_URI=http://localhost:8888/callback\n```\n\n### 4. Authentication\n\nOn first run, the server will open a browser window for Spotify authentication. Follow the OAuth flow to authorize the application.\n\n## Usage\n\n### Running the Server\n\n```bash\n# Development mode with inspector\nmcp dev spotify_mcp_server.py\n\n# Or run directly\npython spotify_mcp_server.py\n```\n\n### Available Tools\n\n#### Artist Management\n\n```python\n# Search for artists\nsearch_artists(query=\"The Beatles\", limit=10)\n\n# Get artist details\nget_artist(artist_id=\"3WrFJ7ztbogyGnTHbHJFl2\")\n\n# Get artist albums\nget_artist_albums(artist_id=\"3WrFJ7ztbogyGnTHbHJFl2\", include_groups=\"album,single\")\n\n# Get artist top tracks\nget_artist_top_tracks(artist_id=\"3WrFJ7ztbogyGnTHbHJFl2\", market=\"US\")\n```\n\n#### Album Management\n\n```python\n# Get album details\nget_album(album_id=\"4aawyAB9vmqN3uQ7FjRGTy\", market=\"US\")\n\n# Get album tracks\nget_album_tracks(album_id=\"4aawyAB9vmqN3uQ7FjRGTy\", limit=20)\n\n# Get new releases\nget_new_releases(country=\"US\", limit=20)\n```\n\n#### Playlist Management\n\n```python\n# Create a new playlist\ncreate_playlist(name=\"My New Playlist\", description=\"A great playlist\", public=False)\n\n# Add tracks to playlist\nadd_tracks_to_playlist(playlist_id=\"playlist_id\", track_uris=[\"spotify:track:track_id\"])\n\n# Get user playlists\nget_user_playlists()\n```\n\n#### User Data\n\n```python\n# Get user's top artists\nget_user_top_artists(time_range=\"medium_term\", limit=20)\n\n# Get user's top tracks\nget_user_top_tracks(time_range=\"short_term\", limit=10)\n```\n\n## Project Structure\n\n```\nspotify-mcp/\n\u251c\u2500\u2500 spotify_mcp_server.py # Main MCP server\n\u251c\u2500\u2500 mcp_tools/ # Tool modules\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 artist_tools.py # Artist-related tools\n\u2502 \u251c\u2500\u2500 playlist_tools.py # Playlist-related tools\n\u2502 \u251c\u2500\u2500 albums.py # Album-related tools\n\u2502 \u2514\u2500\u2500 user_tools.py # User-related tools\n\u251c\u2500\u2500 .env # Environment variables\n\u251c\u2500\u2500 .spotify_cache # Spotify OAuth cache\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u2514\u2500\u2500 README.md # This file\n```\n\n## API Reference\n\n### Artist Tools\n\n#### `search_artists`\n\nSearch for artists on Spotify.\n\n**Parameters:**\n\n- `query` (str): Search query for artist name\n- `limit` (int, optional): Maximum number of results (default: 10, max: 50)\n\n**Returns:**\n\n- List of artists with ID, name, popularity, followers, genres, and Spotify URL\n\n#### `get_artist`\n\nGet detailed information about an artist.\n\n**Parameters:**\n\n- `artist_id` (str): Spotify artist ID\n\n**Returns:**\n\n- Detailed artist information including images, genres, and popularity\n\n#### `get_artist_albums`\n\nGet albums for an artist.\n\n**Parameters:**\n\n- `artist_id` (str): Spotify artist ID\n- `include_groups` (str, optional): Album types to include (default: \"album,single\")\n- `limit` (int, optional): Maximum albums to return (default: 20, max: 50)\n\n**Returns:**\n\n- List of albums with details including release date, track count, and cover images\n\n#### `get_artist_top_tracks`\n\nGet top tracks for an artist.\n\n**Parameters:**\n\n- `artist_id` (str): Spotify artist ID\n- `market` (str, optional): Market/country code (default: \"US\")\n\n**Returns:**\n\n- List of top tracks with popularity, duration, and album information\n\n### Album Tools\n\n#### `get_album`\n\nGet detailed information about an album.\n\n**Parameters:**\n\n- `album_id` (str): Spotify album ID\n- `market` (str, optional): Market/country code (default: \"US\")\n\n**Returns:**\n\n- Detailed album information including artists, images, and genres\n\n#### `get_album_tracks`\n\nGet tracks from an album.\n\n**Parameters:**\n\n- `album_id` (str): Spotify album ID\n- `market` (str, optional): Market/country code (default: \"US\")\n- `limit` (int, optional): Maximum tracks to return (default: 20, max: 50)\n- `offset` (int, optional): Starting index (default: 0)\n\n**Returns:**\n\n- List of tracks with track number, duration, and artist information\n\n#### `get_new_releases`\n\nGet new album releases.\n\n**Parameters:**\n\n- `country` (str, optional): Country code (default: \"US\")\n- `limit` (int, optional): Maximum albums to return (default: 20, max: 50)\n- `offset` (int, optional): Starting index (default: 0)\n\n**Returns:**\n\n- List of new release albums with artist and image information\n\n### Playlist Tools\n\n#### `create_playlist`\n\nCreate a new Spotify playlist.\n\n**Parameters:**\n\n- `name` (str): Name of the playlist\n- `description` (str, optional): Description of the playlist\n- `public` (bool, optional): Whether the playlist is public (default: False)\n- `collaborative` (bool, optional): Whether the playlist is collaborative (default: False)\n\n**Returns:**\n\n- Playlist information including ID, name, and Spotify URL\n\n#### `add_tracks_to_playlist`\n\nAdd tracks to an existing playlist.\n\n**Parameters:**\n\n- `playlist_id` (str): Spotify playlist ID\n- `track_uris` (List[str]): List of Spotify track URIs\n\n**Returns:**\n\n- Success status and number of tracks added\n\n#### `get_user_playlists`\n\nGet current user's playlists.\n\n**Parameters:**\n\n- None\n\n**Returns:**\n\n- List of user's playlists with details including track count and privacy settings\n\n### User Tools\n\n#### `get_user_top_artists`\n\nGet user's most listened to artists from Spotify.\n\n**Parameters:**\n\n- `time_range` (str, optional): Time period for top artists (default: \"medium_term\")\n - `\"short_term\"`: Last 4 weeks\n - `\"medium_term\"`: Last 6 months\n - `\"long_term\"`: Several years\n- `limit` (int, optional): Maximum number of artists to return (default: 20, max: 50)\n- `offset` (int, optional): Index of the first artist to return (default: 0)\n\n**Returns:**\n\n- List of top artists with ID, name, popularity, followers, genres, and Spotify URL\n\n#### `get_user_top_tracks`\n\nGet user's most listened to tracks from Spotify.\n\n**Parameters:**\n\n- `time_range` (str, optional): Time period for top tracks (default: \"medium_term\")\n - `\"short_term\"`: Last 4 weeks\n - `\"medium_term\"`: Last 6 months\n - `\"long_term\"`: Several years\n- `limit` (int, optional): Maximum number of tracks to return (default: 20, max: 50)\n- `offset` (int, optional): Index of the first track to return (default: 0)\n\n**Returns:**\n\n- List of top tracks with ID, name, album info, artists, popularity, duration, and Spotify URL\n\n## Development\n\n### Adding New Tools\n\n1. Create a new function in the appropriate tool module (`artist_tools.py`, `playlist_tools.py`, `albums.py`, or `user_tools.py`)\n2. Add the function to the `__init__.py` exports\n3. Create a wrapper function in `spotify_mcp_server.py`\n4. Copy the docstring and register the tool\n\n### Testing\n\n```bash\n# Run the server in development mode\nmcp dev spotify_mcp_server.py\n\n# The MCP Inspector will open at http://localhost:6274\n# Use it to test your tools interactively\n```\n\n## Troubleshooting\n\n### Authentication Issues\n\n- Ensure your `.env` file has the correct Spotify credentials\n- Check that your redirect URI matches exactly: `http://localhost:8888/callback`\n- Clear the `.spotify_cache` file if you encounter token issues\n\n### API Rate Limits\n\n- Spotify has rate limits on API calls\n- The server includes error handling for rate limit responses\n- Consider implementing caching for frequently accessed data\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for Spotify integration",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/nlevy/spotify-mcp-server",
"Issues": "https://github.com/nlevy/spotify-mcp-server/issues",
"Repository": "https://github.com/nlevy/spotify-mcp-server"
},
"split_keywords": [
"ai",
" assistant",
" mcp",
" model-context-protocol",
" spotify"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7079bce47e99a5003e0a209ecfe1afc08f58f40bbb10f92875546bc752197adf",
"md5": "ae88864514561c4c4bcfd93e4d1f2724",
"sha256": "c711482e5fb9a1b97c0d76e90022905911051ae949ecb12da16524c2ca34453f"
},
"downloads": -1,
"filename": "spotify_mcp_server-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae88864514561c4c4bcfd93e4d1f2724",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14187,
"upload_time": "2025-11-07T16:28:06",
"upload_time_iso_8601": "2025-11-07T16:28:06.073805Z",
"url": "https://files.pythonhosted.org/packages/70/79/bce47e99a5003e0a209ecfe1afc08f58f40bbb10f92875546bc752197adf/spotify_mcp_server-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8762515393d6ec59704702b81f3b2e75bb15a56e0bb0e80ef0ad54d926f727e2",
"md5": "f785c7ccacb47c08b3462a580edeee73",
"sha256": "6a0122044e03908b5314b33556dff0343e9a81c436b9c4dcf0ea4a20d12c964a"
},
"downloads": -1,
"filename": "spotify_mcp_server-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "f785c7ccacb47c08b3462a580edeee73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 69349,
"upload_time": "2025-11-07T16:28:07",
"upload_time_iso_8601": "2025-11-07T16:28:07.053024Z",
"url": "https://files.pythonhosted.org/packages/87/62/515393d6ec59704702b81f3b2e75bb15a56e0bb0e80ef0ad54d926f727e2/spotify_mcp_server-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-07 16:28:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nlevy",
"github_project": "spotify-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spotify-mcp-server"
}
JSON
