Spotify MCP Node Server

Instructions

Implementation Reference

• src/player.ts:28-73 (handler)

  The handler function that destructures input args, validates them, constructs Spotify URI if needed, and uses handleSpotifyRequest to interact with Spotify player API for playback.
  handler: async (args, extra: SpotifyHandlerExtra) => { const { uri, type, id, deviceId } = args; if (!uri && (!type || !id)) { return { content: [ { type: 'text', text: 'Error: Must provide either a URI or both a type and ID', isError: true, }, ], }; } let spotifyUri = uri; if (!spotifyUri && type && id) { spotifyUri = `spotify:${type}:${id}`; } await handleSpotifyRequest(async (spotifyApi) => { const device = deviceId || ''; if (!spotifyUri) { await spotifyApi.player.startResumePlayback(device); return; } if (type === 'track') { await spotifyApi.player.startResumePlayback(device, undefined, [ spotifyUri, ]); } else { await spotifyApi.player.startResumePlayback(device, spotifyUri); } }); return { content: [ { type: 'text', text: `Started playing ${type || 'music'} ${id ? `(ID: ${id})` : ''}`, }, ], }; },
• src/player.ts:13-27 (schema)

  Zod schema for playMusic tool inputs: optional uri, type (track/album/artist/playlist), id, and deviceId.
  schema: { uri: z .string() .optional() .describe('The Spotify URI to play (overrides type and id)'), type: z .enum(['track', 'album', 'artist', 'playlist']) .optional() .describe('The type of item to play'), id: z.string().optional().describe('The Spotify ID of the item to play'), deviceId: z .string() .optional() .describe('The Spotify device ID to play on'), },
• src/index.ts:12-14 (registration)

  Registers all tools (including playMusic from playTools) to the MCP server by calling server.tool() for each.
  [...playTools, ...readTools, ...writeTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });
• src/player.ts:130-130 (registration)

  Exports playTools array containing the playMusic tool for use in main server registration.
  export const playTools = [playMusic, playbackAction];
• src/utils.ts:354-389 (helper)

  Helper utility wrapped around Spotify API calls in the playMusic handler; manages authentication, token refresh, and error retry.
  export async function handleSpotifyRequest<T>( action: (spotifyApi: SpotifyApi) => Promise<T>, ): Promise<T> { let config = loadSpotifyConfig(); let spotifyApi: SpotifyApi; try { // If token is expired, refresh first if ( config.accessTokenExpiresAt && config.accessTokenExpiresAt - Date.now() < 60 * 1000 ) { config = await refreshAccessToken(config); } spotifyApi = createSpotifyApi(); return await action(spotifyApi); } catch (error: any) { // If 401, try refresh once if (error?.status === 401 || /401|unauthorized/i.test(error?.message)) { config = await refreshAccessToken(config); cachedSpotifyApi = null; spotifyApi = createSpotifyApi(); return await action(spotifyApi); } // Skip JSON parsing errors as these are actually successful operations const errorMessage = error instanceof Error ? error.message : String(error); if ( errorMessage.includes('Unexpected token') || errorMessage.includes('Unexpected non-whitespace character') || errorMessage.includes('Exponent part is missing a number in JSON') ) { return undefined as T; } // Rethrow other errors throw error; } }