Spotify MCP Server

Instructions

Implementation Reference

• src/mcp/tools/playlists.ts:204-212 (handler)

  The handler function for the MCP 'create_playlist' tool. It parses arguments and delegates the playlist creation to the SpotifyService.

  handler: async (args: any, spotifyService: SpotifyService) => {
    const { token, name, description = "", isPublic = true } = args;
    return await spotifyService.createPlaylist(
      token,
      name,
      description,
      isPublic
    );
  },

• src/mcp/tools/playlists.ts:192-203 (schema)

  Zod-based input schema for the 'create_playlist' tool, defining parameters: token, name, optional description, and optional isPublic.

  schema: createSchema({
    token: commonSchemas.token(),
    name: z.string().describe("Name for the new playlist"),
    description: z
      .string()
      .optional()
      .describe("Description for the playlist"),
    isPublic: z
      .boolean()
      .default(true)
      .describe("Whether the playlist should be public"),
  }),

• src/mcp/tools/playlists.ts:151-213 (registration)

  The complete tool definition object for 'create_playlist' within the playlistTools registry, including title, description, schema, and handler.

    create_playlist: {
      title: "Create Playlist",
      description: `Create a new custom playlist in the user's Spotify library with specified name and settings.
  
  🎯 USE CASES:
  • Build themed playlists for specific moods or activities
  • Create event-specific music collections for parties
  • Organize music discoveries into curated collections
  • Build workout, study, or relaxation playlists
  • Create collaborative playlists for groups and friends
  
  📝 WHAT IT RETURNS:
  • New playlist information with unique Spotify ID
  • Playlist URL for easy sharing and access
  • Creation confirmation with metadata
  • Empty playlist ready for track additions
  • Settings confirmation (public/private, collaborative)
  
  🔍 EXAMPLES:
  • "Create a playlist called 'Summer Vibes 2024'"
  • "Make a private playlist for my workout music"
  • "Create 'Study Sessions' playlist with description"
  • "Build a collaborative playlist for our road trip"
  
  🎵 PLAYLIST CUSTOMIZATION:
  • Custom name and description for context
  • Public or private visibility settings
  • Collaborative options for group contributions
  • Ready for immediate track additions
  • Perfect foundation for curated collections
  
  💡 CREATION STRATEGIES:
  • Use descriptive names for easy discovery
  • Add detailed descriptions for context
  • Consider privacy settings based on content
  • Plan collaborative access for group playlists
  • Create multiple themed playlists for organization
  
  ⚠️ REQUIREMENTS:
  • Valid Spotify access token with playlist-modify-public/private scopes
  • Unique playlist name (duplicates allowed but not recommended)`,
      schema: createSchema({
        token: commonSchemas.token(),
        name: z.string().describe("Name for the new playlist"),
        description: z
          .string()
          .optional()
          .describe("Description for the playlist"),
        isPublic: z
          .boolean()
          .default(true)
          .describe("Whether the playlist should be public"),
      }),
      handler: async (args: any, spotifyService: SpotifyService) => {
        const { token, name, description = "", isPublic = true } = args;
        return await spotifyService.createPlaylist(
          token,
          name,
          description,
          isPublic
        );
      },
    },

• src/spotify.ts:526-547 (helper)

  SpotifyService.createPlaylist method that performs the actual API call to create a playlist for the authenticated user.

  async createPlaylist(
    token: string,
    name: string,
    description: string = "",
    isPublic: boolean = true
  ): Promise<SpotifyPlaylist> {
    const userProfile = await this.getUserProfile(token);
    const userId = userProfile.id;
  
    const data = {
      name,
      description,
      public: isPublic,
    };
    return await this.makeRequest<SpotifyPlaylist>(
      `users/${userId}/playlists`,
      token,
      {},
      "POST",
      data
    );
  }