spotify-mcp-server

A FastMCP 3.0 server that exposes Spotify controls as Model Context Protocol (MCP) tools. Use it in two ways:

Claude Desktop / Claude Code — let Claude control Spotify during a conversation ("play something relaxing", "create a jazz playlist for dinner")
Web app — a mobile-friendly player at /app for playback control, playlist management, and AI playlist generation

---

Tools

| Tool | Description | |---|---| | get_current_track | Metadata for the currently playing track | | play_pause | Play, pause, or toggle playback | | skip_track | Skip to next or previous track | | add_to_queue | Add a track to the playback queue | | get_recommendations | Fetch track recommendations from seed tracks | | get_user_playlists | List the user's playlists | | create_playlist | Create a new empty playlist | | add_to_playlist | Add tracks to an existing playlist | | search_and_add | Search for a track and add it to a playlist | | play_context | Start playback of a playlist, album, or artist | | get_devices | List available Spotify playback devices | | transfer_playback | Transfer playback to a specific device | | switch_user | Switch between pre-authenticated user profiles | | generate_playlist | Generate and populate a playlist from a natural-language prompt (requires Gemini API key) |

---

Prerequisites

| Requirement | Notes | |---|---| | uv ≥ 0.4 | Python package manager | | Python ≥ 3.10 | Managed automatically by uv | | Spotify account | Free or Premium | | Spotify Developer App | Create one here | | Gemini API key | Optional — only needed for generate_playlist |

---

Quick Start

1. Clone the repo

git clone <repo-url> spotify-mcp-server
cd spotify-mcp-server

2. Install dependencies

uv sync

uv downloads Python 3.12, creates a virtual environment, and installs all locked dependencies automatically.

3. Create a Spotify Developer App

Go to developer.spotify.com/dashboard
Click Create App
Add a Redirect URI — use http://127.0.0.1:8888/callback for local use, or https://your-domain/callback for Railway
Note your Client ID and Client Secret

4. Configure credentials

cp .env.example .env

Edit .env:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

# Optional — for AI playlist generation
GEMINI_API_KEY=your_gemini_api_key_here

.env is gitignored. Never commit it.

5. Authenticate with Spotify (one-time)

uv run python scripts/authenticate.py

This opens a browser for Spotify OAuth. After approving, the token is cached in .cache for all subsequent runs.

---

Option A — Claude Desktop (local, stdio)

This runs the server locally on your machine. Claude Desktop launches it automatically when you start a conversation.

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "src/server.py"],
      "cwd": "/absolute/path/to/spotify-mcp-server",
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback"
      }
    }
  }
}

The config file is located at:

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

Restart Claude Desktop after saving. The Spotify tools will appear automatically in your next conversation.

Example prompts for Claude:

"What's playing on Spotify?"
"Skip this track"
"Create a playlist called Dinner Jazz and add 10 tracks"
"Generate a playlist of 10 summer hits from 2024"

---

Option B — Railway (cloud, web app + MCP)

Deploy to Railway to get a persistent URL accessible from any device, including mobile.

1. Fork and connect

Fork this repo to your GitHub account
Create a new Railway project and connect your fork
Railway will detect the Dockerfile and deploy automatically

2. Set environment variables in Railway

| Variable | Value | |---|---| | SPOTIFY_CLIENT_ID | From Spotify Developer Dashboard | | SPOTIFY_CLIENT_SECRET | From Spotify Developer Dashboard | | SPOTIFY_REDIRECT_URI | https://your-railway-domain/callback | | MCP_TRANSPORT | sse | | GEMINI_API_KEY | Optional — for AI playlist generation |

3. Add the redirect URI to Spotify

In your Spotify Developer App settings, add https://your-railway-domain/callback as an allowed Redirect URI and click Save.

4. Authenticate

Visit https://your-railway-domain/auth/login in a browser to complete the Spotify OAuth flow. The token is stored on the Railway volume at /data/.cache.

5. Access the web app

Open https://your-railway-domain/app on any device — desktop or mobile.

Web app features:

Now Playing card with album art and progress bar
Play / pause / skip / queue controls
Device picker — switch playback between laptop, phone, Bluetooth speakers
Search and add tracks to playlists
Create playlists and browse your library
AI playlist generation from natural-language prompts (requires Gemini API key)

Connect Claude Desktop to the Railway server

You can also point Claude Desktop at the Railway deployment instead of running the server locally:

{
  "mcpServers": {
    "spotify": {
      "type": "http",
      "url": "https://your-railway-domain/mcp"
    }
  }
}

---

Multi-user / Family Accounts

The server supports multiple pre-authenticated Spotify accounts on the same deployment.

One-time setup per user:

Each family member visits: `` https://your-railway-domain/auth/login?user=theirname ` and logs in with their own Spotify account. Their token is stored as .cache-theirname` on the Railway volume.

Switching accounts:

Call the switch_user tool with the profile name, or ask Claude: > "Switch to mum's Spotify account"

Switch back to the default account with switch_user("default").

Note: Spotify limits development apps to 25 users. Beyond that, submit your app for extended quota mode (free, requires review).

---

Project Structure

.
├── src/
│   └── server.py          # FastMCP server + all tool definitions
├── static/
│   └── index.html         # Mobile web app (served at /app)
├── config/
│   └── settings.py        # pydantic-settings config loader
├── scripts/
│   └── authenticate.py    # One-time local OAuth helper
├── .env.example           # Credential template
├── Dockerfile             # Railway deployment
├── railway.json           # Railway configuration
├── pyproject.toml         # Dependencies (managed by uv)
├── uv.lock                # Locked dependency graph
└── CLAUDE.md              # Project conventions

---

License

MIT

spotify-mcp-server