Spotify MCP Server

Instructions

Implementation Reference

• src/play.ts:380-411 (handler)

  The async handler function that destructures args, calls handleSpotifyRequest to invoke spotifyApi.player.setPlaybackVolume with the rounded volumePercent on the optional deviceId, returns success message or error.

  handler: async (args, _extra: SpotifyHandlerExtra) => {
    const { volumePercent, deviceId } = args;
  
    try {
      await handleSpotifyRequest(async (spotifyApi) => {
        await spotifyApi.player.setPlaybackVolume(
          Math.round(volumePercent),
          deviceId || '',
        );
      });
  
      return {
        content: [
          {
            type: 'text',
            text: `Volume set to ${Math.round(volumePercent)}%`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error setting volume: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  },

• src/play.ts:369-379 (schema)

  Zod input schema validating volumePercent as a number between 0 and 100, and optional deviceId string.

  schema: {
    volumePercent: z
      .number()
      .min(0)
      .max(100)
      .describe('The volume to set (0-100)'),
    deviceId: z
      .string()
      .optional()
      .describe('The Spotify device ID to set volume on'),
  },

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

  The setVolume tool is registered by being included in the exported playTools array, which collects all playback-related MCP tools.

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