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

TableJSON 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);

Spotify MCP Server