# Spotify MCP

Spotify MCP server with OAuth authentication, built on Cloudflare Workers.

Connect your Spotify account to a compatible remote MCP client to search music, manage your library and playlists, and control playback. The server is not exclusive to Grok: client support depends on remote HTTP MCP and OAuth capabilities.

## Features

- Search tracks, albums, artists, and playlists.
- Read and manage liked songs, saved albums, and playlists.
- Inspect playback, queue, and available devices.
- Control playback and queue tracks (subject to Spotify account and device requirements).
- Per-user Spotify authorization, token refresh, and encrypted token storage in Workers KV.

## Documentation

- [Deployment and recovery](docs/recovery.md): deploy your own instance or restore an existing one.
- [AI handoff](docs/ai-handoff.md): context and checks for an assistant or future maintainer.

## Quick start

You need Node.js LTS, a Cloudflare account, and a Spotify developer application.

```sh
npm ci
npx wrangler login
npx wrangler whoami
```

Configure your own account and KV namespaces in [wrangler.jsonc](wrangler.jsonc), then add the three required Worker secrets:

```sh
npx wrangler secret put SPOTIFY_CLIENT_ID
npx wrangler secret put SPOTIFY_CLIENT_SECRET
npx wrangler secret put APP_ENCRYPTION_SECRET
npx wrangler types
npx tsc --noEmit
npm test -- --run
npx wrangler deploy
```

The configuration currently contains the maintainer's deployment identifiers. Replace them when deploying to a different account; they are identifiers, not credentials. Follow the [complete setup instructions](docs/recovery.md) before deploying.

Register this exact redirect URI in your Spotify application:

```text
https://<your-worker>.<your-subdomain>.workers.dev/spotify/callback
```

Then add this server URL to your MCP client and complete Spotify authorization:

```text
https://<your-worker>.<your-subdomain>.workers.dev/mcp
```

## Project structure

```text
src/        Worker entrypoint, Spotify integration, tools, and authorization UI
test/       Automated tests
scripts/    Optional live, read-only verification helper
docs/       Deployment, recovery, and maintainer notes
```

## Security and backups

Credentials belong in Cloudflare Worker secrets, never in this repository. Source code is not a backup of live KV data or secrets. Keep your Cloudflare account, Spotify application, and encryption key available to preserve existing authorizations. Do not upload local environment files, tokens, caches, or dependency folders.

## Origin

Based on [guirguispierre/spotifyMCP](https://github.com/guirguispierre/spotifyMCP), with Spotify API compatibility fixes, additional tests, and recovery documentation. This repository does not declare an additional license for the upstream code.