Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/playlists.ts:329-379 (registration)

  Definition of the 'search_playlists' tool including title, description, schema, and handler. This object is part of playlistTools exported and included in the main tools registry.
  search_playlists: { title: "Search Playlists", description: `Search for public playlists using keywords, themes, or specific criteria to discover curated music collections. 🎯 USE CASES: • Discover playlists for specific moods, activities, or genres • Find curated music collections for events or occasions • Explore community-created playlists and music trends • Research popular playlist themes and curation styles • Find inspiration for creating your own playlist collections 📝 WHAT IT RETURNS: • Ranked playlist results based on search relevance • Playlist names, descriptions, and creator information • Follower counts, track counts, and playlist popularity • Playlist artwork and last modification dates • Links to explore and follow discovered playlists 🔍 EXAMPLES: • "Search for 'workout motivation' playlists" • "Find playlists with 'indie rock' in the title" • "Look for 'chill studying' playlist collections" • "Search for 'party music' playlists with many followers" 🔍 SEARCH STRATEGIES: • Use activity keywords: "running", "studying", "party" • Include genre terms: "jazz", "electronic", "country" • Try mood descriptors: "chill", "upbeat", "melancholy" • Combine terms: "indie folk acoustic", "90s hip hop" • Search for seasonal themes: "summer", "holiday", "spring" 💡 DISCOVERY BENEFITS: • Access to expertly curated music collections • Discover new artists through themed playlists • Find music for specific activities or moods • Learn about playlist curation and organization • Connect with music communities and trends ⚠️ REQUIREMENTS: • Valid Spotify access token • Results limited to public playlists only`, schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("playlists (name, keywords)"), limit: commonSchemas.limit(1, 50, 20), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, query, limit = 20 } = args; return await spotifyService.searchPlaylists(token, query, limit); }, },
• src/mcp/tools/playlists.ts:370-374 (schema)

  Input schema for the search_playlists tool defining parameters: token (Spotify access token), query (search string), limit (optional, default 20, max 50).
  schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("playlists (name, keywords)"), limit: commonSchemas.limit(1, 50, 20), }),
• src/mcp/tools/playlists.ts:375-378 (handler)

  Handler function for the MCP tool 'search_playlists' that validates args via schema and calls SpotifyService.searchPlaylists.
  handler: async (args: any, spotifyService: SpotifyService) => { const { token, query, limit = 20 } = args; return await spotifyService.searchPlaylists(token, query, limit); },
• src/spotify.ts:587-598 (helper)

  Core implementation in SpotifyService that performs the HTTP request to Spotify's /search endpoint with type=playlist, returning search results.
  async searchPlaylists( token: string, query: string, limit: number = 20 ): Promise<SearchResult> { const params = { q: query, type: "playlist", limit: Math.min(limit, 50), }; return await this.makeRequest<SearchResult>("search", token, params); }