Spotify MCP Server

Instructions

Implementation Reference

• src/play.ts:222-269 (handler)

  The handler function implements the core logic: validates input, converts track IDs to URIs, calls Spotify API to add items to playlist, handles success/error responses.

  handler: async (args, _extra: SpotifyHandlerExtra) => {
    const { playlistId, trackIds, position } = args;
  
    if (trackIds.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: 'Error: No track IDs provided',
          },
        ],
      };
    }
  
    try {
      const trackUris = trackIds.map((id) => `spotify:track:${id}`);
  
      await handleSpotifyRequest(async (spotifyApi) => {
        await spotifyApi.playlists.addItemsToPlaylist(
          playlistId,
          trackUris,
          position,
        );
      });
  
      return {
        content: [
          {
            type: 'text',
            text: `Successfully added ${trackIds.length} track${
              trackIds.length === 1 ? '' : 's'
            } to playlist (ID: ${playlistId})`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error adding tracks to playlist: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  },

• src/play.ts:211-221 (schema)

  Input schema using Zod for validation: requires playlistId and trackIds array, optional position.

  name: 'addTracksToPlaylist',
  description: 'Add tracks to a Spotify playlist',
  schema: {
    playlistId: z.string().describe('The Spotify ID of the playlist'),
    trackIds: z.array(z.string()).describe('Array of Spotify track IDs to add'),
    position: z
      .number()
      .nonnegative()
      .optional()
      .describe('Position to insert the tracks (0-based index)'),
  },

• src/play.ts:499-510 (registration)

  The addTracksToPlaylist tool is registered in the exported playTools array.

  export const playTools = [
    playMusic,
    pausePlayback,
    skipToNext,
    skipToPrevious,
    createPlaylist,
    addTracksToPlaylist,
    resumePlayback,
    addToQueue,
    setVolume,
    adjustVolume,
  ];