mcp-spotify

Tony-ArtZ/mcp-spotify

3.3

If you are the rightful owner of mcp-spotify and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that integrates Spotify with OAuth authorization flow.

Tools
9
Resources
0
Prompts
0

Spotify MCP Server

A Model Context Protocol (MCP) server that provides Spotify integration with OAuth authorization flow based on the Model Context Protocol specification.

Files

  • index.ts - MCP server setup and tool registration with StreamableHTTPServerTransport
  • spotify.ts - Spotify API service with token management
  • auth.ts - BetterAuth configuration with Drizzle adapter
  • db/ - Database schema and connection using Drizzle ORMotocol (MCP) server that provides Spotify integration with OAuth authorization flow based on the Model Context Protocol specification.

Features

  • OAuth Authorization Flow: Implements MCP's authorization specification with Spotify OAuth
  • Streaming HTTP Transport: Uses MCP's StreamableHTTPServerTransport for efficient communication
  • Automatic Token Refresh: Handles Spotify access token expiration and refresh automatically
  • Simple Architecture: Clean separation between authentication, Spotify API calls, and MCP tools
  • Comprehensive Spotify Tools: Multiple tools for controlling Spotify playback

Available Tools

Playback Control

  • getCurrentlyPlaying - Get information about the currently playing track
  • pausePlayback - Pause Spotify playback
  • resumePlayback - Resume Spotify playback
  • skipToNext - Skip to the next track
  • skipToPrevious - Skip to the previous track
  • setVolume - Set playback volume (currently defaults to 50%)

Track Discovery

  • searchTracks - Search for tracks on Spotify
  • playTrack - Play specific tracks (enhanced functionality coming)

User Info

  • getUserProfile - Get user's Spotify profile information

Architecture

Files

  • index.ts - MCP server setup and tool registration
  • spotify.ts - Spotify API service with token management
  • auth.ts - Better Auth configuration
  • db/ - Database schema and connection

Token Management

The SpotifyService class automatically handles:

  • Token expiry checking (with 5-minute buffer)
  • Automatic token refresh using refresh tokens
  • Database updates for new tokens
  • Error handling for failed refreshes

Key Features

  • Token Refresh: Automatically refreshes tokens before they expire
  • Database Integration: Uses Drizzle ORM with PostgreSQL for token storage
  • Error Handling: Graceful handling of API errors and token issues
  • Session Management: Secure session handling with Better Auth

Setup

  1. Set environment variables:

    SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

  2. Configure database connection in db/index.ts

  3. Run database migrations:

    bun run drizzle-kit push

  4. Start the server:

    bun run index.ts

Usage

  1. Navigate to http://localhost:3000/sign-in to authenticate with Spotify
  2. Use the MCP tools through your MCP client
  3. The server automatically handles token refresh in the background

Technical Notes

  • Uses BetterAuth with Drizzle adapter for OAuth flow with Spotify
  • Implements the MCP Authorization specification for secure authentication
  • Utilizes StreamableHTTPServerTransport for efficient communication
  • Stores tokens securely in PostgreSQL database via Drizzle ORM
  • Clean separation of concerns between authentication, API calls, and MCP tools

Installation

To install dependencies:

bun install

To run:

bun run index.ts

This project was created using bun init in bun v1.2.13. Bun is a fast all-in-one JavaScript runtime.

License

MIT License