search_and_play_music
Search for a track on Spotify and begin playback immediately. This tool combines music search and playback in one operation for voice commands, quick access, and automation workflows.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| query | Yes | Search query for the track to find and play |
Implementation Reference
- src/mcp/tools/search.ts:121-130 (handler)The handler function that executes the tool: destructures args, calls spotifyService.searchMusic, plays the first track found, or throws error if none.
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)The Zod input schema for the tool, requiring Spotify token and search query.
schema: createSchema({ token: commonSchemas.token(), query: commonSchemas.searchQuery("the track to find and play"), }), - src/mcp/tools/index.ts:22-36 (registration)Registration of all tools including searchTools (which contains search_and_play_music) into the central allTools registry used by ToolRegistrar.
export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, }; - src/spotify.ts:479-491 (helper)SpotifyService.searchMusic helper method called by the tool handler to perform the search API call.
async searchMusic( token: string, query: string, type: "track" | "album" | "artist" | "playlist" = "track", limit: number = 10 ): Promise<SearchResult> { const params = { q: query, type: type, limit: Math.min(limit, 50), }; return await this.makeRequest<SearchResult>("search", token, params); } - src/spotify.ts:630-652 (helper)SpotifyService.playMusic helper method called by the tool handler to start playback of the selected track.
async playMusic( token: string, trackUris: string | string[] | null = null, contextUri: string | null = null, deviceId: string | null = null ): Promise<void> { const data: Record<string, any> = {}; if (trackUris) { data.uris = Array.isArray(trackUris) ? trackUris : [`spotify:track:${this.extractId(trackUris)}`]; } if (contextUri) { data.context_uri = contextUri; } const endpoint = deviceId ? `me/player/play?device_id=${deviceId}` : "me/player/play"; return await this.makeRequest<void>(endpoint, token, {}, "PUT", data);