Skip to content

README.md

Latest commit

 

History

History
141 lines (108 loc) · 3.77 KB

README.md

File metadata and controls

141 lines (108 loc) · 3.77 KB

spotify-mcp 🎵

A remote Spotify MCP App — an MCP server that renders a fully interactive player UI directly inside MCP-Apps-capable hosts like Claude, ChatGPT, and Goose.

Built on the MCP Apps spec (@modelcontextprotocol/ext-apps) and served over HTTP using StreamableHTTPServerTransport.

What it does

  • 🎵 Now Playing — album art, track info, progress bar, play/pause/skip/seek
  • 🔍 Search — search tracks, artists, albums, playlists with one-click play/queue
  • 📋 Queue — see what's up next
  • 🔀 Shuffle, repeat, volume control
  • 📂 Playlist management (list, create, add tracks)

Architecture

Host (Claude / ChatGPT / Goose)
│
├── POST https://your-server.com/mcp  (MCP StreamableHTTP)
│
├── Server calls Spotify Web API, returns result + ui:// resource URI
│
├── Host fetches ui://spotify/player → renders player.html in iframe
│
└── Iframe ↔ Host ↔ Server  (bidirectional — button clicks call MCP tools)

Local Development

pnpm install
cp .env.example .env   # fill in your Spotify credentials

Since Spotify requires a real HTTPS redirect URI, use a tunnel for local OAuth:

# Using cloudflared (free, no account needed):
cloudflared tunnel --url http://localhost:3124

# Or ngrok:
ngrok http 3124

Set your .env redirect URI to the tunnel URL:

SPOTIFY_REDIRECT_URI=https://xxxx.trycloudflare.com/auth/callback

Add that same URL to your Spotify app's Redirect URIs in the dashboard, then:

pnpm dev          # starts server with hot reload on http://localhost:3124

Visit http://localhost:3124/auth to authenticate, then connect Claude:

claude mcp add spotify --transport http http://localhost:3124/mcp

Setup

1. Spotify Developer App

  1. Go to developer.spotify.com/dashboard
  2. Create a new app, check Web API
  3. Add your redirect URI: https://your-server.com/auth/callback
  4. Copy your Client ID and Client Secret

2. Deploy the server

Railway (recommended):

railway login
railway init
railway up

Docker (any host):

docker build -t spotify-mcp .
docker run -p 3124:3124 --env-file .env spotify-mcp

Fly.io:

fly launch
fly deploy

Set these environment variables on your host:

SPOTIFY_CLIENT_ID=...
SPOTIFY_CLIENT_SECRET=...
SPOTIFY_REDIRECT_URI=https://your-server.com/auth/callback
PORT=3124

3. Authenticate with Spotify

Visit https://your-server.com/auth in your browser. It'll redirect to Spotify, you'll log in, and tokens are saved on the server. Tokens auto-refresh from then on.

4. Connect your MCP host

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "spotify": {
      "url": "https://your-server.com/mcp"
    }
  }
}

Claude Code:

claude mcp add spotify --transport http https://your-server.com/mcp

Available Tools

Tool Description
open_spotify_player Opens the interactive player UI
search_spotify Search tracks, artists, albums, playlists
get_playback_state Get current playback info
control_playback Play, pause, next, prev, seek, volume, shuffle, repeat
add_to_queue Add a track to the queue
get_queue Get the playback queue (UI-callable only)
manage_playlists List, create, or add tracks to playlists

Example prompts

  • "Open Spotify" → launches the player UI
  • "Search for something chill to work to" → opens search with results
  • "Pause the music" → calls control_playback { action: "pause" }
  • "Create a playlist called 'Focus' and add the top 5 lo-fi tracks"