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;
    }
  }