start_playback
Initiate music playback on Spotify by specifying tracks, albums, playlists, or artists. Use cases include smart space integration, voice commands, custom controllers, and mood-based playlists. Returns playback confirmation, track info, device details, and error status.
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 |
|---|---|---|---|
| contextUri | No | ||
| deviceId | No | Spotify device ID (optional, uses active device if not specified) | |
| token | Yes | Spotify access token for authentication | |
| trackUris | No |
Implementation Reference
- src/mcp/tools/playback.ts:95-103 (handler)The handler function for the start_playback MCP tool. It parses the arguments and delegates to SpotifyService.playMusic method.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)Input schema for the start_playback tool defining token, optional contextUri, trackUris, and deviceId using Zod.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/mcp/tools/index.ts:22-36 (registration)Registration of all tools including playbackTools (containing start_playback) into the allTools registry used by ToolRegistrar.export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/spotify.ts:630-653 (helper)SpotifyService.playMusic method, the core logic that makes the PUT request to Spotify API /me/player/play endpoint to start playback.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/server.ts:49-80 (registration)MCP server request handler for CallToolRequestSchema, which uses ToolRegistrar to execute any tool by name, including start_playback.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, }; } });