# Spotify MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Spotify Web API.

## Features

- **Authentication**: OAuth 2.0 with PKCE support
- **Search**: Search for tracks, artists, albums, and playlists
- **Playback Control**: Play, pause, skip, seek, volume control, and more
- **Content Retrieval**: Get detailed information about tracks, artists, albums, and playlists

## Setup

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Create a Spotify App:
   - Go to https://developer.spotify.com/dashboard
   - Create a new app
   - Add `http://127.0.0.1:8888/callback` to the Redirect URIs (or `http://localhost:8888/callback`)
   - Copy your Client ID and Client Secret

4. Set up environment variables:
   ```bash
   cp .env.example .env
   ```
   Edit `.env` and add your Spotify credentials:
   ```
   SPOTIFY_CLIENT_ID=your_client_id_here
   SPOTIFY_CLIENT_SECRET=your_client_secret_here
   SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
   SPOTIFY_PERSIST_TOKENS=false
   ```

5. Build the project:
   ```bash
   npm run build
   ```

## Usage

### Running the Server

```bash
npm start
```

For development with auto-reload:
```bash
npm run dev
```

### Available Tools

#### Authentication Tools

- `spotify_auth_url`: Generate OAuth authorization URL
- `spotify_exchange_code`: Exchange authorization code for tokens
- `spotify_set_tokens`: Manually set access tokens
- `spotify_refresh_token`: Refresh the access token

#### Search Tools

- `spotify_search`: Search for content on Spotify
  - Parameters: query, type (track/artist/album/playlist), limit

#### Content Tools

- `spotify_get_track`: Get track details
- `spotify_get_artist`: Get artist details
- `spotify_get_album`: Get album details
- `spotify_get_playlist`: Get playlist details

#### Playback Control Tools

- `spotify_play`: Start or resume playback
- `spotify_pause`: Pause playback
- `spotify_next`: Skip to next track
- `spotify_previous`: Skip to previous track
- `spotify_seek`: Seek to position in track
- `spotify_set_volume`: Set playback volume
- `spotify_get_playback_state`: Get current playback state
- `spotify_get_devices`: Get available devices
- `spotify_transfer_playback`: Transfer playback to another device
- `spotify_toggle_shuffle`: Toggle shuffle mode
- `spotify_set_repeat`: Set repeat mode (track/context/off)

### Authentication Flow

1. Use `spotify_auth_url` to generate an authorization URL with desired scopes
2. Direct user to the URL to authorize the app
3. After authorization, use `spotify_exchange_code` with the code and state from the callback
4. The server will automatically manage token refresh when needed

**Important for WSL Users**: The callback URL (`http://127.0.0.1:8888/callback`) won't automatically open in WSL. After authorizing in your browser, you'll be redirected to a URL that may not load. Copy the entire URL from your browser's address bar and paste it back to the LLM to complete the authentication process.

### Token Persistence

By default, authentication tokens are stored only in memory and will be lost when the server restarts. To enable persistent token storage:

1. Set the environment variable `SPOTIFY_PERSIST_TOKENS=true`
2. Tokens will be securely stored in your home directory (`~/.spotify-mcp-tokens.json`)
3. The server will automatically load saved tokens on startup
4. Tokens are saved with proper file permissions (readable only by the owner)

**Security Note**: Tokens are stored in plaintext in your home directory. Only enable persistence if you trust the security of your system.

### Example Usage with Claude Desktop

Add the server to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/path/to/spotify-mcp/dist/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "SPOTIFY_PERSIST_TOKENS": "false"
      }
    }
  }
}
```

### Configuration with Claude CLI

When using Claude CLI, configure the MCP server with the built JavaScript file:

```bash
claude mcp add spotify node /path/to/spotify-mcp/dist/index.js
```

**Important**: Make sure to use the compiled JavaScript file from the `dist/` directory, not the TypeScript source. The server requires Node.js to run and will automatically load environment variables from the `.env` file in the project root.

## Required Scopes

Different features require different OAuth scopes:

- Basic search and content retrieval: No user scopes needed (uses Client Credentials)
- Playback control: `user-modify-playback-state`, `user-read-playback-state`
- User profile: `user-read-private`, `user-read-email`
- Library access: `user-library-read`, `user-library-modify`
- Playlist management: `playlist-read-private`, `playlist-modify-public`, `playlist-modify-private`

## Development

### Project Structure

```
spotify-mcp/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── auth.ts           # OAuth authentication logic
│   └── playback-tools.ts # Playback control tools
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Building

```bash
npm run build
```

### Testing

The server uses stdio transport for communication with MCP clients. You can test it using any MCP-compatible client.

## License

ISC