LibreChat-AI/spotify-mcp

Spotify MCP OAuth Server

This is a fork of Stytch's MCP Consumer TODO List example, adapted to demonstrate Spotify OAuth 2.0 integration with Model Context Protocol (MCP) using Cloudflare Workers.

Why This Fork?

The original Stytch example provided an excellent foundation for implementing OAuth discovery and Dynamic Client Registration for MCP servers. We forked this project to:

1. Leverage the OAuth Discovery Pattern: The original implementation showed how to create OAuth discovery endpoints that work with MCP Inspector
2. Replace Stytch with Spotify: Demonstrate how to integrate with a third-party OAuth provider (Spotify) that doesn't natively support Dynamic Client Registration
3. Focus on the API Layer: While the original included a full TODO app with frontend components, this fork focuses primarily on the MCP server implementation

What's Changed

API Layer Updates

• New Files Added:

  • api/SpotifyMCP.ts - MCP server implementation for Spotify Web API
  • api/SpotifyService.ts - Service layer for Spotify API interactions
  • api/lib/spotify-auth.ts - OAuth flow implementation for Spotify

• Modified Files:

  • api/index.ts - Updated to handle Spotify OAuth flow and MCP endpoints
  • Environment variables changed from Stytch to Spotify credentials

Key Features

This implementation provides:

• OAuth 2.0 Authorization Code Flow with PKCE support
• OAuth Discovery Endpoint at /.well-known/oauth-authorization-server
• Dynamic Client Registration for MCP Inspector compatibility
• Automatic Token Refresh when access tokens expire
• Full Spotify Web API Integration via MCP tools
• Cloudflare Durable Objects for MCP server state management

Architecture

The project uses:

• Cloudflare Workers for the backend API
• Cloudflare Durable Objects for MCP server instances
• Spotify Web API for music data and playback control
• Model Context Protocol (MCP) for AI agent integration

Important: Development Example

⚠️ This server is primarily designed for development and testing OAuth flows with MCP clients.

This implementation is optimized for:

• Testing with LibreChat - An open-source AI chat platform with MCP support
• Development with MCP Inspector - Official MCP debugging tool
• Learning how to implement OAuth discovery for MCP servers

Not Production-Ready

Before deploying to production, you should:

1. Add Authentication Validation

   • Implement proper client validation in the /register endpoint
   • Add rate limiting to prevent abuse
   • Validate redirect URIs against a whitelist

2. Enhance Security

   • Implement CSRF protection
   • Add request signing/verification
   • Use secure session management
   • Implement proper error handling that doesn't leak sensitive information

3. Add Monitoring & Logging

   • Implement comprehensive logging
   • Add error tracking (e.g., Sentry)
   • Monitor API usage and rate limits
   • Track OAuth flow completion rates

4. Optimize for Scale

   • Implement caching strategies
   • Add database for persistent storage (instead of KV for production data)
   • Implement proper connection pooling
   • Add request queuing for rate-limited operations

5. Handle Edge Cases

   • Implement proper retry logic with exponential backoff
   • Handle Spotify API maintenance windows
   • Add graceful degradation for non-critical features
   • Implement proper timeout handling

What's Already Production-Ready

Thanks to the original Stytch implementation, this project already includes:

✅ Cloudflare Workers Deployment

• Full Workers configuration with wrangler.jsonc
• Durable Objects setup for MCP server instances
• Workers KV integration for data storage
• Proper TypeScript configuration for Workers environment

✅ Infrastructure Foundation

• SSE (Server-Sent Events) implementation for real-time MCP communication
• Proper CORS handling
• Environment variable management
• Build and deployment scripts

This means you already have a solid infrastructure foundation - you just need to add the security and monitoring layers mentioned above for production use.

Production Deployment Checklist

If you plan to use this in production:

• Review and implement all security considerations
• Add comprehensive error handling
• Implement proper logging and monitoring
• Add automated tests
• Set up CI/CD pipeline
• Configure production environment variables securely
• Implement backup and recovery procedures
• Add API versioning strategy
• Create documentation for your specific implementation
• Implement user consent and data privacy compliance

MCP Inspector Compatibility

Following the pattern from PayPal's MCP server, this implementation provides:

1. OAuth Discovery at /.well-known/oauth-authorization-server
2. Dynamic Client Registration at /register endpoint
3. Authorization Proxy that redirects to Spotify's OAuth system

This allows MCP Inspector and other MCP clients to automatically discover and register with our server, even though Spotify itself doesn't support Dynamic Client Registration.

Setup

1. Create a Spotify App

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Note your Client ID and Client Secret
4. Add redirect URIs for your application (e.g., http://localhost:3000/callback)

2. Configure Environment Variables

Create a .dev.vars file based on .dev.vars.template:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

3. Install Dependencies

npm install

4. Run Locally

npm run dev

The MCP server will be available at http://localhost:3000/sse

Environment Variables for Vite

The vite.config.ts file supports additional environment variables for development:

• VITE_PORT: Customize the development server port (default: 3000)

  VITE_PORT=8080 npm run dev
  

• VITE_ALLOWED_HOSTS: Specify allowed hosts for the dev server (useful when using tunneling services)

  VITE_ALLOWED_HOSTS="localhost,your-ngrok-domain.ngrok-free.app" npm run dev
  

HTTPS Requirements

The Problem

The Spotify Web API requires HTTPS for OAuth callbacks, and modern browsers enforce secure connections between MCP clients and servers to prevent mixed content issues.

Solutions by Deployment Type

Production Deployment (Recommended)

✅ Cloudflare Workers Solution

• MCP Server: Deploy to Cloudflare Workers - automatic HTTPS included

  • Your deployed server: https://your-worker.workers.dev
  • Permanent, stable HTTPS URLs
  • No additional SSL configuration required
  • Global edge network for fast response times

• MCP Client: Most production MCP clients already run over HTTPS

• Spotify App: Update redirect URIs to use your Workers domain (one-time setup)

# Deploy to get permanent HTTPS URL
npm run deploy

# Update Spotify app redirect URI to:
# https://your-worker.workers.dev/callback

Local Development

🔧 ngrok Solution for Local Testing

When developing locally, use ngrok to create HTTPS tunnels:

1. Install ngrok

# Download from https://ngrok.com/download or use package manager
brew install ngrok  # macOS
# or
snap install ngrok  # Linux

2. Start Your Local MCP Server

# Start with allowed hosts configuration
VITE_ALLOWED_HOSTS="localhost,*.ngrok-free.app" npm run dev

3. Create HTTPS Tunnels

For local development, you may need tunnels for both server and client:

# Terminal 1: Tunnel for MCP Server (port 3000)
ngrok http 3000

# Terminal 2: Tunnel for LibreChat if running locally (port 3080)
ngrok http 3080

4. Configure for Development Session

After starting ngrok, you'll get temporary HTTPS URLs:

• MCP Server: https://abc123.ngrok-free.app
• LibreChat: https://def456.ngrok-free.app

Update your Spotify app for this development session:

1. Go to Spotify Developer Dashboard
2. Add the ngrok redirect URI: https://abc123.ngrok-free.app/callback
3. Configure MCP client to use: https://abc123.ngrok-free.app/sse

Comparison: Production vs Development

Recommended Workflow

1. Start with Production: Deploy to Cloudflare Workers first for stable testing
2. Use Local When Needed: Use ngrok only when you need to test local code changes
3. Hybrid Approach: Keep production deployment for stable testing, use local for active development

ngrok Limitations (Development Only)

• Temporary Domains: URLs change each restart (requires updating Spotify app)
• Session Limits: 2-hour sessions on free plan
• Request Limits: 40 requests per minute on free plan
• Multiple Tunnels: Need separate ngrok instances for server and client

Production Considerations

✅ Cloudflare Workers Benefits:

• Automatic HTTPS with valid certificates
• Global CDN for low latency
• Built-in DDoS protection
• 99.9% uptime SLA
• Easy custom domain support

For Enterprise Use:

• Custom domains: mcp.yourcompany.com
• Enhanced security with Cloudflare WAF
• Advanced analytics and monitoring
• Team collaboration features

OAuth Flow

How It Works with MCP Inspector

1. Discovery: MCP Inspector fetches /.well-known/oauth-authorization-server
2. Registration: Inspector registers itself at /register endpoint
3. Authorization: User is redirected to /authorize, which redirects to Spotify
4. User Consent: User authorizes on Spotify's page
5. Token Exchange: Inspector exchanges code at /token
6. Access MCP: Inspector uses tokens to access MCP endpoints via SSE

Available MCP Tools

The Spotify MCP server exposes the following tools:

Search

• searchTracks - Search for tracks
• searchArtists - Search for artists
• searchAlbums - Search for albums
• searchPlaylists - Search for playlists

User Profile

• getCurrentUserProfile - Get current user's profile

Playback Control

• getCurrentPlayback - Get current playback state
• pausePlayback - Pause playback
• resumePlayback - Resume playback
• skipToNext - Skip to next track
• skipToPrevious - Skip to previous track

Playlists

• getUserPlaylists - Get user's playlists
• getPlaylistTracks - Get tracks from a playlist
• createPlaylist - Create a new playlist
• addTracksToPlaylist - Add tracks to a playlist

User Data

• getRecentlyPlayed - Get recently played tracks
• getTopTracks - Get user's top tracks
• getTopArtists - Get user's top artists

Example Usage

Using MCP Inspector

1. Open MCP Inspector:

   npx @modelcontextprotocol/inspector@latest
   

2. Set Transport Type to SSE
3. Enter URL: http://localhost:3000/sse
4. Click Connect
5. Follow the OAuth flow when redirected

Manual Token Usage

If you prefer to bypass the OAuth flow for testing:

1. Get tokens using the manual flow
2. In MCP Inspector, add headers:
   • Authorization: Bearer YOUR_ACCESS_TOKEN
   • X-Spotify-Refresh-Token: YOUR_REFRESH_TOKEN

Deployment

Quick Deploy to Cloudflare Workers

🚀 Automatic HTTPS Solution

Deploying to Cloudflare Workers automatically solves the HTTPS requirement:

# 1. Set your Spotify credentials
wrangler secret put SPOTIFY_CLIENT_ID
wrangler secret put SPOTIFY_CLIENT_SECRET

# 2. Deploy (gets automatic HTTPS)
npm run deploy

# 3. Update Spotify app redirect URI to your new Workers URL
# Example: https://your-worker.workers.dev/callback

Your MCP server will be available at: https://your-worker.workers.dev/sse

⚠️ Remember: This is a development example. See the "Important: Development Example" section above for production considerations.

Production Deployment

For actual production use:

1. Fork this repository
2. Implement the security enhancements listed above
3. Add proper monitoring and error handling
4. Consider using Cloudflare's paid features:
   • Durable Objects for better state management
   • Workers KV for caching
   • Rate limiting rules
   • Web Application Firewall (WAF)

Security Considerations

1. Client Credentials: Never expose your Spotify Client Secret in client-side code
2. Token Storage: Store tokens securely and use HTTPS for all communications
3. Scopes: Only request the minimum scopes necessary for your application
4. PKCE: The implementation supports PKCE for added security
5. Client Registration: In production, consider adding validation to the registration endpoint

Spotify API Gotchas

1. HTTPS Requirement

• Spotify Web API requires HTTPS for OAuth callbacks
• Solution: Deploy to Cloudflare Workers for automatic HTTPS
• Local Development: Use ngrok for HTTPS tunneling
• Mixed content errors occur when client and server use different protocols

2. Active Device Requirement

• Playback control endpoints (pausePlayback, resumePlayback, etc.) require an active Spotify device
• Users must have Spotify open on at least one device (desktop app, mobile, or web player)
• API returns 404 "No active device found" if no device is available

3. Premium Account Limitations

• Many playback control features require a Spotify Premium account
• Free accounts can read data but cannot control playback
• The API returns 403 "Premium required" errors for free accounts

4. Rate Limiting

• Spotify implements rate limiting on all endpoints
• Limits vary by endpoint but typically allow 180 requests per minute
• Implement exponential backoff for 429 (Too Many Requests) responses

5. Token Expiration

• Access tokens expire after 1 hour
• This implementation handles automatic refresh, but ensure refresh tokens are stored
• Refresh tokens can become invalid if unused for extended periods

6. Scope Requirements

• Different endpoints require different OAuth scopes
• Missing scopes result in 403 Forbidden errors
• Common required scopes:
  • user-read-private - User profile access
  • user-read-playback-state - Current playback info
  • user-modify-playback-state - Playback control
  • playlist-read-private - Access user playlists
  • playlist-modify-public - Create/modify playlists

7. Market Restrictions

• Some content is restricted by geographic market
• API may return different results based on user's country
• Use the market parameter when searching to get region-appropriate results

Acknowledgments

This project is based on the excellent Stytch MCP Consumer TODO List example, which demonstrated how to implement OAuth discovery for MCP servers. We've adapted their pattern to work with Spotify's OAuth system.

Resources

• Spotify Web API Documentation
• OAuth 2.0 Authorization Code Flow
• Model Context Protocol
• Cloudflare Workers Documentation
• Original Stytch Example