https://github.com/ejfox/vulpes-spotify-mcp
https://github.com/ejfox/vulpes-spotify-mcp
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/ejfox/vulpes-spotify-mcp
- Owner: ejfox
- Created: 2025-03-22T22:40:13.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-22T22:40:16.000Z (about 1 year ago)
- Last Synced: 2025-04-06T04:18:00.739Z (about 1 year ago)
- Language: TypeScript
- Size: 23.4 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Vuples Spotify MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Spotify, allowing them to search for and play tracks.
## Features
- Search for tracks by artist, title, or any query
- Play tracks directly on your active Spotify device
- Get information about your currently playing track
- Find available Spotify playback devices
- Combined search-and-play functionality
- List user's Spotify playlists
- View tracks within playlists
- Play playlists (with optional shuffle mode)
- Find and play playlists by name
## Requirements
- Node.js (v16+)
- Spotify Developer Account
- Spotify Premium account (for playback functionality)
- An MCP-compatible client (e.g., Claude Desktop)
## Installation
1. Clone this repository:
```bash
git clone https://github.com/yourusername/spotify-mcp.git
cd spotify-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Create a `.env` file with your Spotify API credentials:
```
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888
# Optional: For playback control
SPOTIFY_REFRESH_TOKEN=your_refresh_token
```
You can get your Client ID and Secret from the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/applications).
4. Generate a refresh token (required for playback control):
There are two ways to get a refresh token:
**Option 1: Use the built-in script**
```bash
npm run get-token
```
This will start a local server and provide instructions in the terminal.
**Option 2: Use the simple script (if option 1 doesn't work)**
```bash
node src/simple-auth.js
```
This will give you a URL to open in your browser. After authorizing, you'll be redirected to a URL. Copy that URL back to the terminal, and it will show you a curl command to get the refresh token.
Required scopes (already included in the scripts):
- `user-read-playback-state`
- `user-modify-playback-state`
- `user-read-currently-playing`
- `playlist-read-private`
- `playlist-read-collaborative`
5. Add the refresh token to your `.env` file:
```
SPOTIFY_REFRESH_TOKEN=your_refresh_token
```
6. Build the project:
```bash
npm run build
```
## Usage with Claude Desktop
1. First, ensure Spotify is open and playing on your device
2. Add this server to your Claude Desktop configuration:
Edit your `claude_desktop_config.json` file (typically in `~/Library/Application Support/Claude/` on macOS or `%APPDATA%\\Claude\\` on Windows):
```json
{
"mcpServers": {
"spotify": {
"command": "node",
"args": ["/absolute/path/to/vulpes-spotify-mcp/dist/index.js"],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id",
"SPOTIFY_CLIENT_SECRET": "your_client_secret",
"SPOTIFY_REDIRECT_URI": "http://localhost:8888",
"SPOTIFY_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}
```
Make sure to replace `/absolute/path/to/vulpes-spotify-mcp` with the actual path to your project.
3. Restart Claude Desktop
4. You should now see the Spotify tools available when you click on the hammer icon in Claude Desktop
## Available Tools
- **spotify-search**: Search for tracks by query
- **spotify-play**: Play a specific track by ID or URI
- **spotify-currently-playing**: Get information about the currently playing track
- **spotify-devices**: List available Spotify playback devices
- **spotify-search-and-play**: Search for a track and automatically play the top result
- **spotify-playlists**: Get a list of the user's Spotify playlists
- **spotify-playlist-tracks**: Get tracks from a specific playlist
- **spotify-play-playlist**: Play a specific playlist (with optional shuffle)
- **spotify-find-playlist**: Find a playlist by name and play it (recommended for AI use)
## Troubleshooting
- **"No active device found"**: Make sure Spotify is open and playing on at least one of your devices
- **"Missing permissions"**: Your refresh token may not have the required scopes
- **"Not premium"**: Playback control requires a Spotify Premium account
- **"Issues with refresh token"**: If your token expires, generate a new one using the steps in the installation section
## Important Notes
1. Always ensure Spotify is open on at least one device before using playback controls
2. The refresh token in your `.env` file and Claude Desktop config must match
3. After making changes to your configuration, restart Claude Desktop
## License
MIT