Spotify MCP Server

Instructions

Implementation Reference

• src/tools/play.ts:3-19 (handler)

  The main handler function for the 'play_playlist' tool. Searches for a playlist by name using the Spotify client, then plays it on the specified device.

  export async function playPlaylist(client: SpotifyClient, playlistName: string, deviceId?: string) {
    const playlist = await client.findPlaylistByName(playlistName);
    
    if (!playlist) {
      throw new Error(`Playlist "${playlistName}" not found`);
    }
  
    await client.playPlaylist(playlist.uri, deviceId);
    return {
      success: true,
      message: `Playing playlist: ${playlist.name}`,
      playlist: {
        id: playlist.id,
        name: playlist.name,
      },
    };
  }

• src/server.ts:54-71 (schema)

  Tool schema definition including name, description, and input schema for the 'play_playlist' tool, provided in the ListTools response.

  {
    name: 'play_playlist',
    description: 'Play a Spotify playlist by name',
    inputSchema: {
      type: 'object',
      properties: {
        playlistName: {
          type: 'string',
          description: 'Name of the playlist to play',
        },
        deviceId: {
          type: 'string',
          description: 'Optional device ID to play on',
        },
      },
      required: ['playlistName'],
    },
  },

• src/server.ts:260-274 (registration)

  Registration and dispatch logic in the CallToolRequestSchema handler: imports playTools and calls playPlaylist function with parsed arguments.

  case 'play_playlist':
    const playlistResult = await playTools.playPlaylist(
      client,
      args?.playlistName as string,
      deviceManager.getDevice(args?.deviceId as string | undefined)
    );
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(playlistResult, null, 2),
        },
      ],
    };

• src/spotify/client.ts:105-111 (helper)

  Low-level SpotifyClient helper method that actually starts playback of a playlist URI using the Spotify Web API.

  async playPlaylist(playlistUri: string, deviceId?: string) {
    const api = await this.getApi();
    await api.play({
      context_uri: playlistUri,
      device_id: deviceId,
    });
  }

• src/spotify/client.ts:29-38 (helper)

  Helper method in SpotifyClient to find a user's playlist by approximate name match.

    const playlists = await this.getCurrentUserPlaylists();
    const normalizedName = name.toLowerCase().trim();
    
    const playlist = playlists.find(p => 
      p.name.toLowerCase().includes(normalizedName) ||
      normalizedName.includes(p.name.toLowerCase())
    );
    
    return playlist || null;
  }