start_playback
Initiate Spotify music playback for tracks, albums, playlists, or artists. Use this tool to start music on smart devices, create voice-activated requests, or build custom music interfaces.
Instructions
Initiate music playback with specific tracks, albums, playlists, or artist collections.
🎯 USE CASES: • Start playing music when users enter smart spaces • Create voice-activated music requests • Build custom music controllers and interfaces • Implement mood-based automatic music selection • Start themed playlists for events, workouts, or activities
📝 WHAT IT RETURNS: • Confirmation of playback initiation • Current track information and playback state • Device information where playback started • Error details if playback couldn't start • Queue information showing what will play next
🔍 EXAMPLES: • "Play my Discover Weekly playlist" • "Start playing the album 'Abbey Road'" • "Play tracks by The Beatles on my laptop" • "Begin playback of my liked songs"
🎵 PLAYBACK OPTIONS: • contextUri: Play entire albums, playlists, or artist catalogs • trackUris: Play specific individual tracks in order • deviceId: Choose which device should start playing • Can resume from where you left off or start fresh
⚠️ REQUIREMENTS: • Valid Spotify access token with user-modify-playback-state scope • User must have an active Spotify device available • Content must be available in user's market
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| contextUri | No | ||
| trackUris | No | ||
| deviceId | No | Spotify device ID (optional, uses active device if not specified) |
Implementation Reference
- src/mcp/tools/playback.ts:95-103 (handler)The core handler function for the 'start_playback' MCP tool. It destructures the input arguments and delegates to SpotifyService.playMusic to initiate playback.handler: async (args: any, spotifyService: SpotifyService) => { const { token, contextUri, trackUris, deviceId } = args; return await spotifyService.playMusic( token, trackUris, contextUri, deviceId ); },
- src/mcp/tools/playback.ts:83-94 (schema)Zod-based input schema for the 'start_playback' tool, defining parameters for token, context URI, track URIs, and target device.schema: createSchema({ token: commonSchemas.token(), contextUri: z .string() .optional() .describe("Spotify context URI (album, playlist, artist) to play"), trackUris: z .array(z.string()) .optional() .describe("Array of specific track URIs to play"), deviceId: commonSchemas.deviceId(), }),
- src/spotify.ts:630-652 (helper)Supporting method in SpotifyService that performs the actual Spotify API call to start playback (/me/player/play), handling track URIs, context URI, and device targeting.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);
- src/mcp/tools/index.ts:22-36 (registration)Registration of all tools, including playbackTools (which contains start_playback), into the central allTools registry used by ToolRegistrar for MCP server integration.export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/mcp/server.ts:49-80 (registration)MCP server request handler for calling any tool (including start_playback) via ToolRegistrar's createToolHandler, which wraps the original handler with validation.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { const toolHandler = toolRegistrar.createToolHandler(name); const result = await toolHandler(args || {}); return { content: [ { type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error executing tool '${name}': ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } });