Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/playback.ts:6-47 (registration)

  Registration of the 'get_currently_playing' MCP tool, defining its title, description, input schema (token), and handler that delegates to SpotifyService.getCurrentPlayback

    get_currently_playing: {
      title: "Get Currently Playing Track",
      description: `Get real-time information about what's currently playing in the user's Spotify session.
  
  🎯 USE CASES:
  • Display "Now Playing" information in applications
  • Track listening history and habits in real-time
  • Create social media posts about current music
  • Build music discovery features based on current listening
  • Monitor playback state for automation and smart home integration
  
  📝 WHAT IT RETURNS:
  • Currently playing track with artist and album information
  • Playback progress (current position vs. total duration)
  • Playback state (playing, paused, stopped)
  • Active device information and volume level
  • Shuffle and repeat mode settings
  • Track popularity and explicit content flags
  
  🔍 EXAMPLES:
  • "What song is currently playing?"
  • "Show me my current playback status"
  • "Get the current track and how much time is left"
  • "What device am I listening on right now?"
  
  💡 REAL-TIME FEATURES:
  • Updates instantly as tracks change
  • Shows exact playback position down to milliseconds
  • Indicates if user is actively listening or paused
  • Perfect for building live music widgets
  
  ⚠️ REQUIREMENTS:
  • Valid Spotify access token with user-read-playback-state scope
  • User must have an active Spotify session`,
      schema: createSchema({
        token: commonSchemas.token(),
      }),
      handler: async (args: any, spotifyService: SpotifyService) => {
        const { token } = args;
        return await spotifyService.getCurrentPlayback(token);
      },
    },

• src/mcp/tools/playback.ts:43-46 (handler)

  Handler function for the 'get_currently_playing' tool. Parses args for token and calls SpotifyService.getCurrentPlayback(token).

  handler: async (args: any, spotifyService: SpotifyService) => {
    const { token } = args;
    return await spotifyService.getCurrentPlayback(token);
  },

• src/mcp/tools/playback.ts:40-42 (schema)

  Input schema for the tool, requiring a Spotify access token.

  schema: createSchema({
    token: commonSchemas.token(),
  }),

• src/spotify.ts:600-602 (helper)

  Core implementation in SpotifyService: makes authenticated GET request to Spotify API endpoint '/me/player' to fetch current playback state.

  async getCurrentPlayback(token: string): Promise<CurrentPlayback | null> {
    return await this.makeRequest<CurrentPlayback | null>("me/player", token);
  }

• src/spotify.ts:124-139 (schema)

  TypeScript interface defining the structure of the current playback response from Spotify API.

  export interface CurrentPlayback {
    device: SpotifyDevice;
    repeat_state: "off" | "track" | "context";
    shuffle_state: boolean;
    context: {
      type: string;
      href: string;
      external_urls: { spotify: string };
      uri: string;
    } | null;
    timestamp: number;
    progress_ms: number | null;
    is_playing: boolean;
    item: SpotifyTrack | null;
    currently_playing_type: "track" | "episode" | "ad" | "unknown";
  }