Ramona668/spotify-mcp-server

Spotify MCP Server (Minimal Template, Secure Redirect Ready)

This is a minimal, MCP-style Spotify server you can deploy quickly (Vercel-ready). It handles Spotify OAuth and exposes a small set of REST endpoints that many MCP clients or agent runtimes can call to control Spotify via the Web API.

Important redirect note (2025)
Spotify no longer accepts http://localhost for OAuth redirects.
For local dev, use loopback IP with HTTP: http://127.0.0.1:<PORT> (or http://[::1]:<PORT>).
For production, use HTTPS (e.g., your Vercel domain).

What you get

• OAuth login with Spotify (/auth → Spotify consent → /callback).
• Token storage in memory (swap in Redis/KV for production).
• Tool discovery at /mcp/tools.
• Tool execution at /mcp/execute supporting:
  • search (query tracks)
  • play (start/resume on your active device)
  • pause
  • next
  • prev
  • create_playlist (and add tracks)

Quick start (local)

1. Create a Spotify app: https://developer.spotify.com/dashboard

   • Add a Redirect URI: http://127.0.0.1:8888/callback

2. Copy .env.example to .env and fill in values.

3. Install & run:

npm install
npm run dev

4. Visit: http://127.0.0.1:8888/auth
   After successful auth, you can call tools:

# Discover tools
curl http://127.0.0.1:8888/mcp/tools

# Search
curl -X POST http://127.0.0.1:8888/mcp/execute -H "Content-Type: application/json" -d '{"tool":"search","args":{"q":"lofi chill"}}'

Deploy to Vercel

1. Push this folder to a new GitHub repo.
2. In Vercel → "New Project" → Import your repo.
3. Set Environment Variables:
   • SPOTIFY_CLIENT_ID
   • SPOTIFY_CLIENT_SECRET
   • SPOTIFY_REDIRECT_URI → https://YOUR-VERCEL-APP.vercel.app/callback
   • SESSION_SECRET → any random string
4. Deploy. Your MCP base URL will be: https://YOUR-VERCEL-APP.vercel.app

Environment Variables

See .env.example for required values.

Security & Persistence

• This demo stores tokens in memory (Node process). For production, use a KV/DB like Redis.
• Lock down CORS if exposing publicly.
• Scope permissions only as needed.

Adapting to strict MCP transports

Some MCP clients may require:

• JSON-RPC over stdio or WebSocket
• Tool schema registration
• Session/handshake messages

You can:

• Expose a WebSocket at /mcp/socket and implement JSON-RPC.
• Or run a companion adapter that converts REST tools to the client's expected transport.

Endpoints

• GET /auth → redirect to Spotify OAuth
• GET /callback → handles Spotify auth; stores tokens
• GET /mcp/tools → returns available tools JSON
• POST /mcp/execute → executes a tool by name with args
• POST /logout → clears session

Scopes used

user-read-playback-state
user-modify-playback-state
user-read-currently-playing
playlist-modify-private
playlist-modify-public
playlist-read-private
user-read-email

License

MIT