Spotify MCP Server

A remote Model Context Protocol server that provides full coverage of the Spotify Web API. Built with Bun, Hono, and Supabase.

Live server: sptfy-mcp.online

Quick Setup

Claude.ai

1. Go to Customize > Connectors > Add Custom Connector
2. Set Name to Spotify and URL to https://sptfy-mcp.online/mcp
3. Save and authorize with your Spotify account

Claude Desktop / Claude Code / Cursor

Add to your MCP client config:

{
  "mcpServers": {
    "spotify": {
      "type": "streamable-http",
      "url": "https://sptfy-mcp.online/mcp"
    }
  }
}

On first connection you'll be guided through Spotify authorization — no API keys or local setup needed.

Features

• 80 tools covering the Spotify Web API
• Remote MCP via Streamable HTTP transport — no local install required
• OAuth2 proxy with PKCE support and dynamic client registration
• Automatic token refresh — Spotify tokens are refreshed transparently
• Encrypted storage — all Spotify tokens encrypted at rest with AES-256-GCM
• Supabase backend — persistent storage for tokens, sessions, and clients
• Tool analytics — anonymous usage tracking with 90-day retention
• Scheduled cleanup — automatic purge of expired tokens, sessions, and analytics
• Landing page with live health status

Tools

Category	Tools	Examples
Albums	7	Get album, saved albums, save/remove/check
Artists	4	Get artist, top tracks, albums
Audiobooks	7	Get audiobook, chapters, save/remove
Chapters	2	Get chapter details
Episodes	6	Get episode, save/remove/check
Library	3	Save/remove/check library items (unified)
Markets	1	Available markets
Player	15	Play, pause, skip, seek, queue, devices, volume
Playlists	12	Create, modify, add/remove items, cover images
Search	1	Search with field filters across all types
Shows	7	Get show, episodes, save/remove/check
Tracks	6	Get track, saved tracks, save/remove/check
Users	10	Profile, top items, follow/unfollow

All save/remove/check library operations use the new unified Spotify /me/library endpoint with Spotify URIs.

Prerequisites

• Bun v1.3+
• A Spotify Developer App
• A Supabase project

Setup

1. Clone and install

git clone https://github.com/akutishevsky/spotify-mcp.git
cd spotify-mcp
bun install

2. Configure environment

cp .env.example .env

Fill in the values:

Variable	Description
SPOTIFY_CLIENT_ID	From your Spotify Developer Dashboard
SPOTIFY_CLIENT_SECRET	From your Spotify Developer Dashboard
SPOTIFY_REDIRECT_URI	Must match your Spotify app settings (e.g. http://localhost:3000/callback)
ENCRYPTION_SECRET	32-byte hex key — generate with bun run generate:secret
SUPABASE_URL	Your Supabase project URL
SUPABASE_SECRET_KEY	Your Supabase service role key
PORT	Server port (default: 3000)

3. Run Supabase migrations

Apply the database schema to your Supabase project:

supabase db push

Or run the SQL files manually from supabase/migrations/ in the Supabase SQL editor:

1. 001_initial_schema.sql — Core tables (mcp_tokens, oauth_sessions, auth_codes, registered_clients) with RLS
2. 002_fix_rls_policies.sql — Tighten RLS policies
3. 003_tool_analytics.sql — Tool analytics table with indexes
4. 004_add_granted_scopes.sql — Granted scopes tracking on mcp_tokens

4. Start the server

bun run dev

OAuth Flow

This server acts as an OAuth2 proxy between MCP clients and Spotify:

MCP Client                    Spotify MCP Server                 Spotify
    |                               |                               |
    |-- POST /register ----------->|                               |
    |<-- client_id ----------------|                               |
    |                               |                               |
    |-- GET /authorize ----------->|                               |
    |                               |-- redirect to Spotify ------>|
    |                               |<-- callback with code -------|
    |<-- redirect with MCP code ---|                               |
    |                               |                               |
    |-- POST /token -------------->|                               |
    |                               |-- exchange code ------------>|
    |                               |<-- Spotify tokens -----------|
    |<-- MCP access token ---------|                               |
    |                               |                               |
    |-- POST /mcp (with Bearer) -->|-- Spotify API calls -------->|
    |<-- tool results -------------|<-- API responses ------------|

API Endpoints

Endpoint	Method	Description
/	GET	Landing page with live health status
/register	POST	Dynamic OAuth client registration
/authorize	GET	Start OAuth authorization flow
/callback	GET	Spotify OAuth callback
/token	POST	Exchange auth code for MCP token
/mcp	POST/GET/DELETE	MCP Streamable HTTP transport
/health	GET	Health check (JSON)
/.well-known/oauth-authorization-server	GET	OAuth server metadata

Scripts

bun run dev              # Start with hot reload
bun run start            # Production start
bun run lint             # Run ESLint
bun run lint:fix         # Auto-fix lint issues
bun run format           # Format with Prettier
bun run generate:secret  # Generate encryption key
bun run inspector        # Launch MCP Inspector

Deployment

The server includes a Dockerfile for container-based deployments (e.g. Digital Ocean App Platform). The idleTimeout is set to 255 seconds to support long-lived SSE streams.

License

MIT