Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/search.ts:121-130 (handler)

  The core handler function implementing the tool logic: searches for music tracks matching the query and plays the first result.
  handler: async (args: any, spotifyService: SpotifyService) => { const { token, query } = args; const result = await spotifyService.searchMusic(token, query); if (result.tracks && result.tracks.items.length > 0) { const track_id = result.tracks.items[0].id; const playResult = await spotifyService.playMusic(token, track_id); return playResult; } throw new Error("No tracks found for the search query"); },
• src/mcp/tools/search.ts:117-120 (schema)

  Input schema validating the token and search query parameters.
  schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("the track to find and play"), }),
• src/mcp/tools/search.ts:68-131 (registration)

  Tool registration within the searchTools export, including title, description, schema, and handler.
  search_and_play_music: { title: "Search and Play Music", description: `Instantly search for a track and begin playback in one seamless operation for immediate music gratification. 🎯 USE CASES: • Voice-activated music requests with instant playback • Quick music access without browsing interfaces • Party DJ functionality with instant song requests • Smart home integration with spoken music commands • Emergency music solutions when you need a specific song now 📝 WHAT IT RETURNS: • Search results showing the track that was found • Playback confirmation with current track information • Device information where playback started • Error details if track couldn't be found or played • Alternative suggestions if exact match isn't available 🔍 EXAMPLES: • "Search and play 'Bohemian Rhapsody' by Queen" • "Find and start 'Uptown Funk' immediately" • "Play the first result for 'relaxing piano music'" • "Search 'workout motivation' and start playing" 🎵 SMART PLAYBACK: • Automatically selects the best match from search results • Prioritizes popular and high-quality versions • Starts playback on user's active device • Falls back gracefully if preferred version unavailable • Maintains context for follow-up requests 💡 WORKFLOW OPTIMIZATION: • Eliminates manual track selection step • Perfect for hands-free music control • Reduces interaction friction for immediate needs • Great for mood-based music requests • Ideal for social settings and parties 🚀 INSTANT GRATIFICATION: • No browsing or selection required • Immediate musical response to requests • Perfect for time-sensitive music needs • Streamlined user experience • Ideal for voice and automation interfaces ⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • Active Spotify device must be available • Search query should be specific enough for good matching`, schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("the track to find and play"), }), handler: async (args: any, spotifyService: SpotifyService) => { const { token, query } = args; const result = await spotifyService.searchMusic(token, query); if (result.tracks && result.tracks.items.length > 0) { const track_id = result.tracks.items[0].id; const playResult = await spotifyService.playMusic(token, track_id); return playResult; } throw new Error("No tracks found for the search query"); }, },
• src/mcp/tools/index.ts:22-36 (registration)

  Aggregation of searchTools (including search_and_play_music) into the central allTools registry used by ToolRegistrar.
  export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };