spotify-direct-mcp

A FastMCP server that exposes Spotify as a set of tools for Claude.

Ask Claude things like:

• "What's the full discography of Sade?"
• "What key and BPM is 'Isn't She Lovely' in?"
• "Recommend 20 tracks with the same vibe as Stevie Wonder — high energy, soulful"
• "What am I listening to right now?"
• "Create a private playlist called 'Late Night Drive' from those recommendations"

---

Tools

Tool	Description	Auth required
search_tracks	Search the Spotify catalog	No
get_track_details	Audio features (BPM, key, energy, danceability) + metadata	No
get_artist_discography	Full album/track list for an artist	No
get_recommendations	Mood/seed-based track recommendations	No
get_currently_playing	What's playing on your account right now	Yes
create_playlist	Create a playlist in your account	Yes

Note: As of late 2024, Spotify restricts the audio-features and recommendations endpoints to apps approved for "Extended Quota Mode". If your app doesn't have that approval, get_track_details will still return track metadata but audio_features will contain an explanatory message instead of BPM/key data, and get_recommendations will return an error field with the same explanation. Request access at https://developer.spotify.com/documentation/web-api/concepts/quota-modes.

---

Prerequisites

• Python 3.10+ (required by FastMCP and the underlying MCP SDK — see below if you're not sure what you have)
• A Spotify account (free or premium)
• A Spotify Developer app (developer.spotify.com/dashboard)

Checking your Python version

python3 --version

If this prints 3.10.x, 3.11.x, 3.12.x, or 3.13.x, you're good — skip to Step 1.

If it prints 3.9.x or lower (common on macOS, which ships an old system Python), you need to install a newer Python before creating the virtual environment in Step 2. pip install -r requirements.txt will fail with Could not find a version that satisfies the requirement fastmcp>=2.0 if you try to use Python 3.9 or earlier.

Installing Python 3.10+

macOS (Homebrew):

brew install python@3.12

This installs a separate python3.12 binary alongside your system Python — it won't replace or break anything else. Verify with:

python3.12 --version

macOS (no Homebrew): Download the installer from python.org/downloads and run it. After installing, use python3.12 (or whichever version you installed) in place of python3 below.

Windows: Download the installer from python.org/downloads, run it, and check "Add python.exe to PATH" during install. Verify with:

python --version

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install python3.12 python3.12-venv

Using pyenv (any OS, if you manage multiple Python versions):

pyenv install 3.12.7
pyenv local 3.12.7   # sets this version for the spotify-direct-mcp directory

Once you have a 3.10+ interpreter available, use that binary (e.g. python3.12) instead of python3 when creating the virtual environment in Step 2.

---

Step 1: Spotify Developer Setup

1. Go to developer.spotify.com/dashboard
2. Click Create app
3. Fill in:
   • App name: spotify-direct-mcp
   • App description: anything
   • Redirect URI: http://localhost:8888/callback
   • Check: Web API
4. Click Save
5. Copy your Client ID and Client Secret from the app settings

---

Step 2: Local Setup

# Clone or copy the project
cd spotify-direct-mcp

# Create virtual environment using Python 3.10+
# If `python3 --version` showed 3.10+, use python3 below.
# Otherwise, substitute the 3.10+ binary you installed above (e.g. python3.12).
python3 -m venv .venv
source .venv/bin/activate        # Mac/Linux
# .venv\Scripts\activate         # Windows

# Confirm the venv is using Python 3.10+
python --version

# Install dependencies
pip install -r requirements.txt

# Copy env template and fill in your credentials
cp .env.example .env

If pip install -r requirements.txt fails with Could not find a version that satisfies the requirement fastmcp>=2.0, your venv was created with Python <3.10. Delete it and recreate using a 3.10+ binary:

rm -rf .venv
python3.12 -m venv .venv   # use whichever 3.10+ binary you installed
source .venv/bin/activate
pip install -r requirements.txt

Edit .env:

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

---

Step 3: OAuth Setup (one-time)

Tools that access your personal account (get_currently_playing, create_playlist) require a one-time OAuth authorization:

python oauth_setup.py

This will:

1. Open a browser window to Spotify's auth page
2. Ask you to authorize the app
3. Redirect you to localhost:8888/callback (the page won't load — that's fine)
4. Ask you to paste the full redirect URL
5. Cache your token to .spotify_cache

You only need to do this once. The token auto-refreshes.

---

Step 4: Run Locally

Option A: stdio (for Claude Desktop)

python server.py
# or explicitly:
python server.py stdio

Option B: SSE (for Railway / remote clients)

python server.py sse
# Server starts on http://localhost:8000

---

Step 5: Connect to Claude Desktop

Add this to your Claude Desktop config file:

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

{
  "mcpServers": {
    "spotify-direct-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/spotify-direct-mcp/server.py"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://localhost:8888/callback"
      }
    }
  }
}

Replace /absolute/path/to/ with your actual paths.

Restart Claude Desktop after saving. You should see spotify-direct-mcp in the tools list.

---

Step 6: Deploy to Railway

First-time setup

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Initialize project
railway init

# Set environment variables
railway variables set SPOTIFY_CLIENT_ID=your_client_id_here
railway variables set SPOTIFY_CLIENT_SECRET=your_client_secret_here
railway variables set SPOTIFY_REDIRECT_URI=https://your-app.railway.app/callback

Update Redirect URI on Spotify

Before deploying, add your Railway URL as an allowed redirect URI in your Spotify app settings:

1. Go to developer.spotify.com/dashboard
2. Click your app → Edit Settings
3. Add https://your-app.railway.app/callback to Redirect URIs
4. Save

Deploy

railway up

Railway reads railway.toml and automatically:

• Detects Python via Nixpacks
• Installs requirements.txt
• Runs python server.py sse
• Sets PORT environment variable

Get your deployed URL

railway domain
# Returns something like: https://spotify-direct-mcp-production.up.railway.app

Connect Claude to your Railway deployment

Once deployed, your MCP server is accessible via SSE at:

https://your-app.railway.app/sse

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "spotify-direct-mcp": {
      "url": "https://your-app.railway.app/sse"
    }
  }
}

---

Important: OAuth on Railway

get_currently_playing and create_playlist require an OAuth token tied to your Spotify account.

The .spotify_cache file generated locally is not automatically available on Railway. You have two options:

Option A (Recommended for personal use): Complete OAuth locally, then set the token contents as a Railway environment variable:

# After running oauth_setup.py locally:
cat .spotify_cache

# Copy the JSON output, then:
railway variables set SPOTIFY_TOKEN_CACHE='{"access_token": "...", ...}'

Then update server.py to read from this env var if the cache file doesn't exist — or simply use the server for catalog tools only (search, details, discography, recommendations) which don't need user auth.

Option B: Use a token refresh endpoint pattern (more complex, not scaffolded here).

For the interview demo, Option A or catalog-only is perfectly sufficient.

---

Project Structure

spotify-direct-mcp/
├── server.py          # FastMCP server — all tools live here
├── oauth_setup.py     # One-time OAuth flow helper
├── requirements.txt   # Python dependencies
├── railway.toml       # Railway deployment config
├── .env.example       # Environment variable template
├── .env               # Your actual credentials (gitignored)
├── .spotify_cache     # OAuth token cache (gitignored)
└── README.md          # This file

---

Example Prompts for Claude

Once connected, try these:

Search for "Isn't She Lovely" and give me the BPM and musical key.

What's Sade's full discography sorted by year?

Recommend 15 tracks similar to Anita Ward with high danceability and moderate energy.

What am I currently listening to? What key is it in?

Create a private playlist called "Sunday Morning Soul" from these track URIs: [paste URIs]

Search for top tracks by Stevie Wonder from the 1970s.

---

Architecture Notes

• Client Credentials flow is used for all catalog tools (no user login required)
• OAuth PKCE flow is used for user-context tools (currently playing, create playlist)
• FastMCP handles the MCP protocol — all tools are decorated with @mcp.tool()
• Transport is switchable: stdio for local/Claude Desktop, sse for Railway/remote
• Railway auto-detects Python via Nixpacks — no Dockerfile needed

---

Built With

• FastMCP — MCP server framework
• Spotipy — Spotify Web API client
• Railway — deployment platform