MCP Claude Spotify

1 
2 
3# MCP Claude Spotify
4[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/imprvhub/mcp-claude-spotify)](https://archestra.ai/mcp-catalog/imprvhub__mcp-claude-spotify)
5[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/99039f16-4abd-4af8-8873-ae2844e7dd65)
6[![smithery badge](https://smithery.ai/badge/@imprvhub/mcp-claude-spotify)](https://smithery.ai/server/@imprvhub/mcp-claude-spotify)
7 
8<table style="border-collapse: collapse; width: 100%;">
9<tr>
10<td style="padding: 15px; vertical-align: middle; border: none; text-align: center;">
11  <a href="https://mseep.ai/app/imprvhub-mcp-claude-spotify">
12    <img src="https://mseep.net/pr/imprvhub-mcp-claude-spotify-badge.png" alt="MseeP.ai Security Assessment Badge" />
13  </a>
14</td>  
15<td style="width: 50%; padding: 15px; vertical-align: middle; border: none;">An integration that allows Claude Desktop to interact with Spotify using the Model Context Protocol (MCP).</td>
16<td style="width: 50%; padding: 0; vertical-align: middle; border: none;"><a href="https://glama.ai/mcp/servers/@imprvhub/mcp-claude-spotify"><img src="https://glama.ai/mcp/servers/@imprvhub/mcp-claude-spotify/badge" alt="Claude Spotify MCP server" style="max-width: 100%;" /></a></td>
17</tr>
18</table>
19 
20## Features
21 
22- Spotify authentication
23- Search for tracks, albums, artists, and playlists
24- Playback control (play, pause, next, previous)
25- Create and manage playlists
26- Get personalized recommendations
27- Access user's top played tracks over different time periods
28 
29## Demo
30 
31<p>
32  <a href="https://www.youtube.com/watch?v=WNw5H9epZfc">
33    <img src="public/assets/preview.png" width="600" alt="Claude Spotify Integration Demo">
34  </a>
35</p>
36 
37## Requirements
38 
39- Node.js 16 or higher
40- Spotify account
41- Claude Desktop
42- Spotify API credentials (Client ID and Client Secret)
43 
44## Installation
45 
46### Installing via Smithery
47 
48To install MCP Claude Spotify for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@imprvhub/mcp-claude-spotify):
49 
50```bash
51npx -y @smithery/cli install @imprvhub/mcp-claude-spotify --client claude
52```
53 
54### Installing Manually
551. Clone or download this repository:
56```bash
57git clone https://github.com/imprvhub/mcp-claude-spotify
58cd claude-spotify-mcp
59```
60 
612. Install dependencies:
62```bash
63npm install
64```
65 
663. Build the project (if you want to modify the source code):
67```bash
68npm run build
69```
70 
71The repository already includes pre-built files in the `build` directory, so you can skip step 3 if you don't plan to modify the source code.
72 
73## Setting up Spotify Credentials
74 
75To use this MCP, you need to obtain Spotify API credentials:
76 
771. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
782. Log in with your Spotify account
793. Click "Create App"
804. Fill in your app information:
81   - App name: "MCP Claude Spotify" (or whatever you prefer)
82   - App description: "Spotify integration for Claude Desktop"
83   - Website: You can leave this blank or put any URL
84   - Redirect URI: **Important** - Add `http://127.0.0.1:8888/callback`
855. Accept the terms and conditions and click "Create"
866. In your app dashboard, you'll see the "Client ID"
877. Click "Show Client Secret" to reveal your "Client Secret"
88 
89Save these credentials as you'll need them for configuration.
90 
91## Running the MCP Server
92 
93There are two ways to run the MCP server:
94 
95### Option 1: Running manually (recommended for first-time setup and troubleshooting)
96 
971. Open a terminal or command prompt
982. Navigate to the project directory
993. Run the server directly:
100 
101```bash
102node build/index.js
103```
104 
105Keep this terminal window open while using Claude Desktop. The server will run until you close the terminal.
106 
107### Option 2: Auto-starting with Claude Desktop (recommended for regular use)
108 
109The Claude Desktop can automatically start the MCP server when needed. To set this up:
110 
111#### Configuration
112 
113The Claude Desktop configuration file is located at:
114 
115- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
116- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
117 
118Edit this file to add the Spotify MCP configuration. If the file doesn't exist, create it:
119 
120```json
121{
122  "mcpServers": {
123    "spotify": {
124      "command": "node",
125      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js"],
126      "env": {
127        "SPOTIFY_CLIENT_ID": "your_client_id_here",
128        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
129      }
130    }
131  }
132}
133```
134 
135**Important**: Replace:
136- `ABSOLUTE_PATH_TO_DIRECTORY` with the **complete absolute path** where you installed the MCP
137  - macOS/Linux example: `/Users/username/mcp-claude-spotify`
138  - Windows example: `C:\\Users\\username\\mcp-claude-spotify`
139- `your_client_id_here` with the Client ID you obtained from Spotify
140- `your_client_secret_here` with the Client Secret you obtained from Spotify
141 
142If you already have other MCPs configured, simply add the "spotify" section inside the "mcpServers" object.
143 
144#### Setting up auto-start scripts (Optional)
145 
146For a more reliable experience, you can set up auto-start scripts:
147 
148<details>
149<summary><b>Windows auto-start instructions</b></summary>
150 
1511. Create a file named `start-spotify-mcp.bat` in the project directory with the following content:
152```
153@echo off
154cd %~dp0
155node build/index.js
156```
157 
1582. Create a shortcut to this BAT file
1593. Press `Win+R`, type `shell:startup` and press Enter
1604. Move the shortcut to this folder to have it start with Windows
161</details>
162 
163<details>
164<summary><b>macOS auto-start instructions</b></summary>
165 
1661. Create a file named `com.spotify.mcp.plist` in `~/Library/LaunchAgents/` with the following content:
167```xml
168<?xml version="1.0" encoding="UTF-8"?>
169<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
170<plist version="1.0">
171<dict>
172    <key>Label</key>
173    <string>com.spotify.mcp</string>
174    <key>ProgramArguments</key>
175    <array>
176        <string>/usr/local/bin/node</string>
177        <string>ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js</string>
178    </array>
179    <key>RunAtLoad</key>
180    <true/>
181    <key>KeepAlive</key>
182    <true/>
183    <key>StandardErrorPath</key>
184    <string>/tmp/spotify-mcp.err</string>
185    <key>StandardOutPath</key>
186    <string>/tmp/spotify-mcp.out</string>
187    <key>EnvironmentVariables</key>
188    <dict>
189        <key>SPOTIFY_CLIENT_ID</key>
190        <string>your_client_id_here</string>
191        <key>SPOTIFY_CLIENT_SECRET</key>
192        <string>your_client_secret_here</string>
193    </dict>
194</dict>
195</plist>
196```
197 
1982. Replace the path and credentials with your actual values
1993. Load the agent with: `launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist`
200</details>
201 
202<details>
203<summary><b>Linux auto-start instructions</b></summary>
204 
2051. Create a file named `spotify-mcp.service` in `~/.config/systemd/user/` (create the directory if it doesn't exist):
206```
207[Unit]
208Description=Spotify MCP Server for Claude Desktop
209After=network.target
210 
211[Service]
212Type=simple
213ExecStart=/usr/bin/node ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
214Restart=on-failure
215Environment="SPOTIFY_CLIENT_ID=your_client_id_here"
216Environment="SPOTIFY_CLIENT_SECRET=your_client_secret_here"
217 
218[Install]
219WantedBy=default.target
220```
221 
2222. Replace the path and credentials with your actual values
2233. Enable and start the service:
224```bash
225systemctl --user enable spotify-mcp.service
226systemctl --user start spotify-mcp.service
227```
228 
2294. Check status with:
230```bash
231systemctl --user status spotify-mcp.service
232```
233</details>
234 
235## Usage
236 
2371. Restart Claude Desktop after modifying the configuration
2382. In Claude, use the `auth-spotify` command to start the authentication process
2393. A browser window will open for you to authorize the application
2404. Log in with your Spotify account and authorize the application
2415. **Important**: After successful authentication, restart Claude Desktop to properly initialize the MCP's tool registry and WebSocket session token cache
2426. After restarting, all Spotify MCP tools will be properly registered and available for use
243 
244The MCP server runs as a child process managed by Claude Desktop. When Claude is running, it automatically starts and manages the Node.js server process based on the configuration in `claude_desktop_config.json`.
245 
246## Available Tools
247 
248### auth-spotify
249Initiates the Spotify authentication process.
250 
251### search-spotify
252Searches for tracks, albums, artists, or playlists.
253 
254**Parameters:**
255- `query`: Search text
256- `type`: Type of search (track, album, artist, playlist)
257- `limit`: Number of results (1-50)
258 
259### play-track
260Plays a specific track.
261 
262**Parameters:**
263- `trackId`: Spotify track ID
264- `deviceId`: (Optional) Spotify device ID to play on
265 
266### get-current-playback
267Gets information about the current playback.
268 
269### pause-playback
270Pauses the playback.
271 
272### next-track
273Skips to the next track.
274 
275### previous-track
276Returns to the previous track.
277 
278### get-user-playlists
279Gets the user's playlists.
280 
281### create-playlist
282Creates a new playlist.
283 
284**Parameters:**
285- `name`: Playlist name
286- `description`: (Optional) Description
287- `public`: (Optional) Whether it's public or private
288 
289### add-tracks-to-playlist
290Adds tracks to a playlist.
291 
292**Parameters:**
293- `playlistId`: Playlist ID
294- `trackIds`: Array of track IDs
295 
296### get-recommendations
297Gets recommendations based on seeds.
298 
299**Parameters:**
300- `seedTracks`: (Optional) Array of track IDs
301- `seedArtists`: (Optional) Array of artist IDs
302- `seedGenres`: (Optional) Array of genres
303- `limit`: (Optional) Number of recommendations (1-100)
304 
305### get-top-tracks
306Gets the user's most played tracks over a specified time range.
307 
308**Parameters:**
309- `limit`: (Optional) Number of tracks to return (1-50, default: 20)
310- `offset`: (Optional) Index of the first track to return (default: 0)
311- `time_range`: (Optional) Time frame for calculating affinity:
312  - `short_term`: Approximately last 4 weeks
313  - `medium_term`: Approximately last 6 months (default)
314  - `long_term`: Several years of data
315 
316## Troubleshooting
317 
318### "Server disconnected" error
319If you see the error "MCP Spotify: Server disconnected" in Claude Desktop:
320 
3211. **Verify the server is running**:
322   - Open a terminal and manually run `node build/index.js` from the project directory
323   - If the server starts successfully, use Claude while keeping this terminal open
324 
3252. **Check your configuration**:
326   - Ensure the absolute path in `claude_desktop_config.json` is correct for your system
327   - Double-check that you've used double backslashes (`\\`) for Windows paths
328   - Verify you're using the complete path from the root of your filesystem
329 
3303. **Try the auto-start option**:
331   - Set up the auto-start script for your operating system as described in the "Setting up auto-start scripts" section
332   - This ensures the server is always running when you need it
333 
334### Browser doesn't open automatically
335If the browser doesn't open automatically during authentication, manually visit:
336`http://127.0.0.1:8888/login`
337 
338### Authentication error
339Make sure you've correctly configured the redirect URI in your Spotify Developer dashboard:
340`http://127.0.0.1:8888/callback`
341 
342### Server startup error
343Verify that:
344- Environment variables are correctly configured in your `claude_desktop_config.json` or launch script
345- Node.js is installed and compatible (v16+)
346- Required ports (8888) are available and not blocked by firewall
347- You have permission to run the script in the specified location
348 
349### Tools not appearing in Claude
350If the Spotify tools don't appear in Claude after authentication:
351- Make sure you've restarted Claude Desktop after successful authentication
352- Check the Claude Desktop logs for any MCP communication errors
353- Ensure the MCP server process is running (run it manually to confirm)
354- Verify that the MCP server is correctly registered in the Claude Desktop MCP registry
355 
356### Checking if the server is running
357To check if the server is running:
358 
359- **Windows**: Open Task Manager, go to the "Details" tab, and look for "node.exe"
360- **macOS/Linux**: Open Terminal and run `ps aux | grep node`
361 
362If you don't see the server running, start it manually or use the auto-start method.
363 
364## Testing
365 
366This project includes automated tests to ensure code quality and functionality. The test suite uses Jest with TypeScript support and covers:
367 
368- Zod schema validation - verifies all input schemas correctly validate data
369- Spotify API interactions - tests API request handling and error handling
370- MCP server functionality - ensures proper registration and execution of tools
371 
372### Running Tests
373 
374First, make sure all development dependencies are installed:
375 
376```bash
377npm install
378```
379 
380To run all tests:
381 
382```bash
383npm test
384```
385 
386To run a specific test file:
387 
388```bash
389npm test -- --testMatch="**/tests/schemas.test.ts"
390```
391 
392If you encounter issues with ESM modules, make sure you're using Node.js v16 or higher and that the NODE_OPTIONS environment variable includes the `--experimental-vm-modules` flag as configured in the package.json.
393 
394### Test Structure
395 
396- `tests/schemas.test.ts`: Tests for input validation schemas
397- `tests/spotify-api.test.ts`: Tests for Spotify API interactions
398- `tests/server.test.ts`: Tests for MCP server functionality
399 
400### Adding New Tests
401 
402When adding new functionality, please include corresponding tests:
403 
4041. For new schemas, add validation tests in `schemas.test.ts`
4052. For Spotify API functions, add tests in `spotify-api.test.ts` 
4063. For MCP tools, add tests in `server.test.ts`
407 
408All tests should be written using Jest and the ESM module format with TypeScript.
409 
410## Security Notes
411 
412- Never share your Client ID and Client Secret
413- Access token is now stored in the user's home directory at `~/.spotify-mcp/tokens.json` to enable persistence between sessions and multiple instances
414- No user data is stored on disk
415 
416### Revoking Application Access
417 
418For security reasons, you may want to revoke the application's access to your Spotify account when:
419- You no longer use this integration
420- You suspect unauthorized access
421- You're troubleshooting authentication issues
422 
423To revoke access:
424 
4251. Go to your [Spotify Account page](https://www.spotify.com/account)
4262. Navigate to "Apps" in the menu
4273. Find "MCP Claude Spotify" (or the name you chose for your app)
4284. Click "REMOVE ACCESS"
429 
430This immediately invalidates all access and refresh tokens. The next time you use the `auth-spotify` command, you'll need to authorize the application again.
431 
432## Contributing
433 
434Contributions are welcome! Here are some guidelines to follow:
435 
436### Development Workflow
437 
4381. Fork the repository
4392. Create a feature branch (`git checkout -b feature/amazing-feature`)
4403. Make your changes
4414. Run tests to ensure they pass (`npm test`)
4425. Commit your changes (`git commit -m 'Add some amazing feature'`)
4436. Push to the branch (`git push origin feature/amazing-feature`)
4447. Open a Pull Request
445 
446### Code Style Guidelines
447 
448This project follows these coding standards:
449 
450- Use TypeScript with strict type checking
451- Follow ESM module format
452- Use 2 spaces for indentation
453- Use camelCase for variables and functions
454- Use PascalCase for classes and interfaces
455- Document functions with JSDoc comments
456- Keep line length under 100 characters
457 
458### Project Structure
459 
460The project follows this structure:
461 
462```
463mcp-claude-spotify/
464├── src/               # Source code
465├── build/             # Compiled JavaScript
466├── tests/             # Test files
467├── public/            # Public assets
468└── ...
469```
470 
471### Pull Request Process
472 
4731. Ensure your code follows the style guidelines
4742. Update documentation if needed
4753. Add tests for new functionality
4764. Make sure all tests pass
4775. Your PR will be reviewed by maintainers
478 
479## Related Links
480 
481- [Model Context Protocol](https://modelcontextprotocol.io/)
482- [Spotify Web API Documentation](https://developer.spotify.com/documentation/web-api)
483- [Claude Desktop](https://claude.ai/download)
484- [MCP Series](https://github.com/mcp-series)
485 
486## License
487 
488This project is licensed under the Mozilla Public License 2.0 - see the [LICENSE](https://github.com/imprvhub/mcp-claude-spotify/blob/main/LICENSE) file for details.
489