# MCP Claude Spotify
[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/imprvhub/mcp-claude-spotify)](https://archestra.ai/mcp-catalog/imprvhub__mcp-claude-spotify)
[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/99039f16-4abd-4af8-8873-ae2844e7dd65)
[![Smithery](https://img.shields.io/badge/Smithery-imprvhub%2Fmcp--claude--spotify-8A2BE2)](https://smithery.ai/server/imprvhub/mcp-claude-spotify)

<table style="border-collapse: collapse; width: 100%;">
<tr>
<td style="padding: 15px; vertical-align: middle; border: none; text-align: center;">
  <a href="https://mseep.ai/app/imprvhub-mcp-claude-spotify">
    <img src="https://mseep.net/pr/imprvhub-mcp-claude-spotify-badge.png" alt="MseeP.ai Security Assessment Badge" />
  </a>
</td>
<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>
<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>
</tr>
</table>

> **Removed in 0.6.0 — `get-recommendations`.** Spotify deprecated `/v1/recommendations`
> on 27 November 2024, along with related-artists, audio-features, audio-analysis,
> featured-playlists and 30-second preview URLs. Apps created after that date get
> `403 Forbidden`, and apps still in development mode lost access too, so the tool could
> not work for essentially anyone. Use `search-spotify` and `get-top-tracks` instead.
> See [Spotify's announcement](https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api).

## Features

- Spotify authentication
- Search for tracks, albums, artists, and playlists
- Playback control (play, pause, next, previous)
- Full playlist management (create, update, delete, reorder tracks, manage cover images)
- Read your top tracks and listening history
- Access user's top played tracks over different time periods
- View recently played tracks

## Demo

<p>
  <a href="https://www.youtube.com/watch?v=WNw5H9epZfc">
    <img src="public/assets/preview.png" width="600" alt="Claude Spotify Integration Demo">
  </a>
</p>

## Requirements

- Node.js 20 or higher
- Spotify account
- Claude Desktop
- Spotify API credentials (Client ID and Client Secret)

## Installation

### Installing via Smithery

To install MCP Claude Spotify for Claude Desktop automatically via [Smithery](https://smithery.ai/server/imprvhub/mcp-claude-spotify):

```bash
npx -y @smithery/cli@latest mcp add imprvhub/mcp-claude-spotify --client claude
```

### Installing Manually
1. Clone or download this repository:
```bash
git clone https://github.com/imprvhub/mcp-claude-spotify
cd claude-spotify-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project (if you want to modify the source code):
```bash
npm run build
```

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

## Setting up Spotify Credentials

To use this MCP, you need to obtain Spotify API credentials:

1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. Log in with your Spotify account
3. Click "Create App"
4. Fill in your app information:
   - App name: "MCP Claude Spotify" (or whatever you prefer)
   - App description: "Spotify integration for Claude Desktop"
   - Website: You can leave this blank or put any URL
   - Redirect URI: **Important** - Add `http://127.0.0.1:8888/callback`
5. Accept the terms and conditions and click "Create"
6. In your app dashboard, you'll see the "Client ID"
7. Click "Show Client Secret" to reveal your "Client Secret"

Save these credentials as you'll need them for configuration.

## Running the MCP Server

There are two ways to run the MCP server:

### Option 1: Authorize once from a terminal (first-time setup)

Claude Desktop starts its own copy of the server, so a server left running in a terminal is
not the one Claude talks to. What a terminal run is useful for is authorizing once: with
`SPOTIFY_AUTO_AUTH=true` and no stored tokens, the server opens the Spotify login in your
browser as soon as it starts.

```bash
SPOTIFY_CLIENT_ID=your_client_id \
SPOTIFY_CLIENT_SECRET=your_client_secret \
SPOTIFY_AUTO_AUTH=true \
node build/index.js
```

Approve the request in the browser. Once the terminal prints "Authorization complete",
stop the process with Ctrl+C. The token is saved to `~/.spotify-mcp/tokens.json`, and the
copy Claude Desktop starts will pick it up.

You can skip this step entirely and ask Claude to "authenticate with Spotify" instead, which
runs the `auth-spotify` tool and opens the same login page.

### Option 2: Auto-starting with Claude Desktop (recommended for regular use)

The Claude Desktop can automatically start the MCP server when needed. To set this up:

#### Configuration

The Claude Desktop configuration file is located at:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Edit this file to add the Spotify MCP configuration. If the file doesn't exist, create it:

```json
{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}
```

**Important**: Replace:
- `ABSOLUTE_PATH_TO_DIRECTORY` with the **complete absolute path** where you installed the MCP
  - macOS/Linux example: `/Users/username/mcp-claude-spotify`
  - Windows example: `C:\\Users\\username\\mcp-claude-spotify`
- `your_client_id_here` with the Client ID you obtained from Spotify
- `your_client_secret_here` with the Client Secret you obtained from Spotify

If you already have other MCPs configured, simply add the "spotify" section inside the "mcpServers" object.

#### Setting up auto-start scripts (Optional)

For a more reliable experience, you can set up auto-start scripts:

<details>
<summary><b>Windows auto-start instructions</b></summary>

1. Create a file named `start-spotify-mcp.bat` in the project directory with the following content:
```
@echo off
cd %~dp0
node build/index.js
```

2. Create a shortcut to this BAT file
3. Press `Win+R`, type `shell:startup` and press Enter
4. Move the shortcut to this folder to have it start with Windows
</details>

<details>
<summary><b>macOS auto-start instructions</b></summary>

1. Create a file named `com.spotify.mcp.plist` in `~/Library/LaunchAgents/` with the following content:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.spotify.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardErrorPath</key>
    <string>/tmp/spotify-mcp.err</string>
    <key>StandardOutPath</key>
    <string>/tmp/spotify-mcp.out</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>SPOTIFY_CLIENT_ID</key>
        <string>your_client_id_here</string>
        <key>SPOTIFY_CLIENT_SECRET</key>
        <string>your_client_secret_here</string>
    </dict>
</dict>
</plist>
```

2. Replace the path and credentials with your actual values
3. Load the agent with: `launchctl load ~/Library/LaunchAgents/com.spotify.mcp.plist`
</details>

<details>
<summary><b>Linux auto-start instructions</b></summary>

1. Create a file named `spotify-mcp.service` in `~/.config/systemd/user/` (create the directory if it doesn't exist):
```
[Unit]
Description=Spotify MCP Server for Claude Desktop
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-spotify/build/index.js
Restart=on-failure
Environment="SPOTIFY_CLIENT_ID=your_client_id_here"
Environment="SPOTIFY_CLIENT_SECRET=your_client_secret_here"

[Install]
WantedBy=default.target
```

2. Replace the path and credentials with your actual values
3. Enable and start the service:
```bash
systemctl --user enable spotify-mcp.service
systemctl --user start spotify-mcp.service
```

4. Check status with:
```bash
systemctl --user status spotify-mcp.service
```
</details>

## Development

```bash
npm install
npm run build
npm test
```

## Usage

1. Restart Claude Desktop after modifying the configuration
2. In Claude, use the `auth-spotify` command to start the authentication process
3. A browser window will open for you to authorize the application
4. Log in with your Spotify account and authorize the application
5. **Important**: After successful authentication, restart Claude Desktop to properly initialize the MCP's tool registry and WebSocket session token cache
6. After restarting, all Spotify MCP tools will be properly registered and available for use

The 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`.

## Security notes

- **Authorization is CSRF-protected.** The login URL carries a random `state` value that
  the callback verifies before exchanging a code. Versions before 0.6.0 sent no `state`,
  so any page open in your browser could hit the loopback callback and bind a different
  Spotify account.
- **The token file is owner-only.** `~/.spotify-mcp/tokens.json` holds a long-lived refresh
  token and is now written mode `600` in a `700` directory. It was previously created with
  the default mode, leaving it readable by every account on the machine.
- **Nothing is killed to free the port.** If port 8888 is busy the server reports it and
  stops. Earlier versions ran `lsof -i:8888 -t | xargs kill -9` (and a `taskkill`
  equivalent on Windows), SIGKILLing whatever unrelated process held that very common
  development port.
- **IDs in tool arguments are validated.** Track, playlist and device IDs go into API paths
  and query strings, so only plain Spotify IDs are accepted; anything else is rejected before a
  request is built.
- **The callback listens on loopback only** (`127.0.0.1`). The previous express listener
  bound every network interface, so anyone on the same network could reach `/login` and
  `/callback`. Containers can widen it with `AUTH_BIND_HOST=0.0.0.0`.
- **The callback server shuts down** once authorization completes, rather than staying
  bound for the rest of the session.

## Available Tools

### Authentication

#### auth-spotify
Initiates the Spotify authentication process.

### Search

#### search-spotify
Searches for tracks, albums, artists, or playlists.

**Parameters:**
- `query`: Search text
- `type`: Type of search (track, album, artist, playlist)
- `limit`: Number of results (1-10, default: 5)

### Playback Control

#### get-current-playback
Gets information about the current playback state.

#### play-track
Plays a specific track on an active device.

**Parameters:**
- `trackId`: Spotify track ID
- `deviceId`: (Optional) Spotify device ID to play on

#### pause-playback
Pauses the current playback.

#### next-track
Skips to the next track.

#### previous-track
Returns to the previous track.

### Playlist Management

#### get-user-playlists
Gets a list of the user's playlists.

**Parameters:**
- `limit`: (Optional) Number of playlists to return (1-50, default: 20)
- `offset`: (Optional) Index of the first playlist to return (default: 0)

#### create-playlist
Creates a new playlist for the current user.

**Parameters:**
- `name`: Playlist name
- `description`: (Optional) Description
- `public`: (Optional) Whether it's public or private

#### update-playlist
Updates a playlist's name, description, public/private status, or collaborative setting.

**Parameters:**
- `playlistId`: Spotify ID of the playlist
- `name`: (Optional) New name for the playlist
- `description`: (Optional) New description for the playlist
- `public`: (Optional) Whether the playlist should be public
- `collaborative`: (Optional) Whether the playlist should be collaborative (must set public to false first)

#### delete-playlist
Unfollows (removes) a playlist from your library. The playlist still exists on Spotify but is no longer in your library.

**Parameters:**
- `playlistId`: Spotify ID of the playlist

#### get-playlist-tracks
Gets the tracks in a playlist with pagination support.

**Parameters:**
- `playlistId`: Spotify ID of the playlist
- `limit`: (Optional) Number of tracks to return (1-50, default: 20)
- `offset`: (Optional) Index of the first track to return (default: 0)

#### add-tracks-to-playlist
Adds tracks to a playlist.

**Parameters:**
- `playlistId`: Playlist ID
- `trackIds`: Array of track IDs

#### remove-tracks-from-playlist
Removes tracks from a playlist.

**Parameters:**
- `playlistId`: Spotify ID of the playlist
- `trackIds`: Array of Spotify track IDs to remove

#### reorder-playlist-tracks
Reorders tracks in a playlist by moving a range of tracks to a new position.

**Parameters:**
- `playlistId`: Spotify ID of the playlist
- `rangeStart`: Position of the first track to move
- `insertBefore`: Position where the tracks should be inserted
- `rangeLength`: (Optional) Number of tracks to move (default: 1)

#### get-playlist-cover
Gets the cover image of a playlist.

**Parameters:**
- `playlistId`: Spotify ID of the playlist

#### upload-playlist-cover
Uploads a custom cover image for a playlist (base64 encoded JPEG, max 256KB).

**Parameters:**
- `playlistId`: Spotify ID of the playlist
- `imageBase64`: Base64 encoded JPEG image

### Discovery & History

#### get-top-tracks
Gets the user's most played tracks over a specified time range.

**Parameters:**
- `limit`: (Optional) Number of tracks to return (1-50, default: 20)
- `offset`: (Optional) Index of the first track to return (default: 0)
- `time_range`: (Optional) Time frame for calculating affinity:
  - `short_term`: Approximately last 4 weeks
  - `medium_term`: Approximately last 6 months (default)
  - `long_term`: Several years of data

#### get-recently-played
Gets the user's recently played tracks.

**Parameters:**
- `limit`: (Optional) Maximum number of tracks to return (1-50, default: 20)
- `before`: (Optional) Unix timestamp in milliseconds. Returns tracks played before this time
- `after`: (Optional) Unix timestamp in milliseconds. Returns tracks played after this time

## Troubleshooting

### "Server disconnected" error
If you see the error "MCP Spotify: Server disconnected" in Claude Desktop:

1. **Verify the server is running**:
   - Open a terminal and manually run `node build/index.js` from the project directory
   - If the server starts successfully, use Claude while keeping this terminal open

2. **Check your configuration**:
   - Ensure the absolute path in `claude_desktop_config.json` is correct for your system
   - Double-check that you've used double backslashes (`\\`) for Windows paths
   - Verify you're using the complete path from the root of your filesystem

3. **Try the auto-start option**:
   - Set up the auto-start script for your operating system as described in the "Setting up auto-start scripts" section
   - This ensures the server is always running when you need it

### Browser doesn't open automatically
If the browser doesn't open automatically during authentication, manually visit:
`http://127.0.0.1:8888/login`

### Authentication error
Make sure you've correctly configured the redirect URI in your Spotify Developer dashboard:
`http://127.0.0.1:8888/callback`

### Server startup error
Verify that:
- Environment variables are correctly configured in your `claude_desktop_config.json` or launch script
- Node.js is installed and compatible (v16+)
- Required ports (8888) are available and not blocked by firewall
- You have permission to run the script in the specified location

### Tools not appearing in Claude
If the Spotify tools don't appear in Claude after authentication:
- Make sure you've restarted Claude Desktop after successful authentication
- Check the Claude Desktop logs for any MCP communication errors
- Ensure the MCP server process is running (run it manually to confirm)
- Verify that the MCP server is correctly registered in the Claude Desktop MCP registry

### Checking if the server is running
To check if the server is running:

- **Windows**: Open Task Manager, go to the "Details" tab, and look for "node.exe"
- **macOS/Linux**: Open Terminal and run `ps aux | grep node`

If you don't see the server running, start it manually or use the auto-start method.

## Testing

This project includes automated tests to ensure code quality and functionality. The test suite uses Jest with TypeScript support and covers:

- Zod schema validation - verifies all input schemas correctly validate data
- Spotify API interactions - tests API request handling and error handling
- MCP server functionality - ensures proper registration and execution of tools

### Running Tests

First, make sure all development dependencies are installed:

```bash
npm install
```

To run all tests:

```bash
npm test
```

To run a specific test file:

```bash
npm test -- --testMatch="**/tests/schemas.test.ts"
```

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

### Test Structure

- `tests/schemas.test.ts`: Tests for input validation schemas
- `tests/spotify-api.test.ts`: Tests for Spotify API interactions
- `tests/server.test.ts`: Tests for MCP server functionality

### Adding New Tests

When adding new functionality, please include corresponding tests:

1. For new schemas, add validation tests in `schemas.test.ts`
2. For Spotify API functions, add tests in `spotify-api.test.ts`
3. For MCP tools, add tests in `server.test.ts`

All tests should be written using Jest and the ESM module format with TypeScript.

## Security Notes

- Never share your Client ID and Client Secret
- Access token is now stored in the user's home directory at `~/.spotify-mcp/tokens.json` to enable persistence between sessions and multiple instances
- No user data is stored on disk

### Revoking Application Access

For security reasons, you may want to revoke the application's access to your Spotify account when:
- You no longer use this integration
- You suspect unauthorized access
- You're troubleshooting authentication issues

To revoke access:

1. Go to your [Spotify Account page](https://www.spotify.com/account)
2. Navigate to "Apps" in the menu
3. Find "MCP Claude Spotify" (or the name you chose for your app)
4. Click "REMOVE ACCESS"

This immediately invalidates all access and refresh tokens. The next time you use the `auth-spotify` command, you'll need to authorize the application again.

## Contributing

Contributions are welcome! Here are some guidelines to follow:

### Development Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests to ensure they pass (`npm test`)
5. Commit your changes (`git commit -m 'Add some amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Code Style Guidelines

This project follows these coding standards:

- Use TypeScript with strict type checking
- Follow ESM module format
- Use 2 spaces for indentation
- Use camelCase for variables and functions
- Use PascalCase for classes and interfaces
- Document functions with JSDoc comments
- Keep line length under 100 characters

### Project Structure

The project follows this structure:

```
mcp-claude-spotify/
├── src/               # Source code
├── build/             # Compiled JavaScript
├── tests/             # Test files
├── public/            # Public assets
└── ...
```

### Pull Request Process

1. Ensure your code follows the style guidelines
2. Update documentation if needed
3. Add tests for new functionality
4. Make sure all tests pass
5. Your PR will be reviewed by maintainers

## Related Links

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Spotify Web API Documentation](https://developer.spotify.com/documentation/web-api)
- [Claude Desktop](https://claude.ai/download)
- [MCP Series](https://github.com/mcp-series)

## License

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