Spotify MCP Node Server

Instructions

Implementation Reference

• src/read.ts:56-124 (handler)

  The core handler function for searchSpotify tool. It takes query, type (track/album/playlist), limit, offset; calls Spotify search API via handleSpotifyRequest; formats results into numbered list with artists, duration/ID; returns markdown text or error.

  handler: async (args, extra: SpotifyHandlerExtra) => {
    const { query, type, limit = 20, offset = 0 } = args;
  
    try {
      const results = await handleSpotifyRequest(async (spotifyApi) => {
        return await spotifyApi.search(
          query,
          [type],
          undefined,
          limit as MaxInt<50>,
          offset,
        );
      });
  
      let formattedResults = '';
  
      if (type === 'track' && results.tracks) {
        formattedResults = results.tracks.items
          .map((track, i) => {
            const artists = track.artists.map((a) => a.name).join(', ');
            const duration = formatDuration(track.duration_ms);
            return `${i + 1}. "${
              track.name
            }" by ${artists} (${duration}) - ID: ${track.id}`;
          })
          .join('\n');
      } else if (type === 'album' && results.albums) {
        formattedResults = results.albums.items
          .map((album, i) => {
            const artists = album.artists.map((a) => a.name).join(', ');
            return `${i + 1}. "${album.name}" by ${artists} - ID: ${album.id}`;
          })
          .join('\n');
      } else if (type === 'playlist' && results.playlists) {
        formattedResults = results.playlists.items
          .map((playlist, i) => {
            return `${i + 1}. "${playlist?.name ?? 'Unknown Playlist'} (${
              playlist?.description ?? 'No description'
            } tracks)" by ${playlist?.owner?.display_name} - ID: ${
              playlist?.id
            }`;
          })
          .join('\n');
      }
  
      return {
        content: [
          {
            type: 'text',
            text:
              formattedResults.length > 0
                ? `# Search results for "${query}" (type: ${type})\n\n${formattedResults}`
                : `No ${type} results found for "${query}"`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error searching for ${type}s: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  },

• src/read.ts:22-55 (schema)

  Input schema using Zod for validation: query (string with search syntax), type (enum track/album/playlist), optional limit (1-50), offset (0-1000). Includes detailed descriptions.

  name: 'searchSpotify',
  description:
    'Search Spotify by keyword and field filters (e.g. artist, track, playlist, tag:new, tag:hipster) and return items of the given type',
  schema: {
    query: z
      .string()
      .describe(
        [
          'Full Spotify search string combining:',
          '- free-text keywords (e.g. “remaster”),',
          '- field filters: artist:<name>, track:<name>, album:<name>,',
          '  year:<YYYY> or <YYYY-YYYY>, genre:<name>.',
          'The album, artist and year filters can be used for album and track types.',
          'The genre filter can only be used for track type.',
          'Special filter tag:hipster (bottom 10% popularity) can be used with track and album types.',
          'All separated by spaces. Example: "tag:hipster artist:Queen remaster".',
        ].join(' '),
      ),
    type: z
      .enum(['track', 'album', 'playlist'])
      .describe('Which item type to return: track, album or playlist'),
    limit: z
      .number()
      .min(1)
      .max(50)
      .optional()
      .describe('Max number of results to return (1-50)'),
    offset: z
      .number()
      .min(0)
      .max(1000)
      .optional()
      .describe('The index of the first item to return. Defaults to 0'),
  },

• src/index.ts:12-14 (registration)

  Registers the searchSpotify tool (included in readTools) with the MCP server by calling server.tool() for each tool in the combined list from playTools, readTools, writeTools.

  [...playTools, ...readTools, ...writeTools].forEach((tool) => {
    server.tool(tool.name, tool.description, tool.schema, tool.handler);
  });

• src/read.ts:521-522 (registration)

  Adds searchSpotify to the readTools array which is later imported and registered in index.ts.

  export const readTools = [
    searchSpotify,

• src/utils.ts:354-389 (helper)

  Helper function used in the handler to execute Spotify API calls with automatic access token refresh on expiry or 401 errors.

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