Spotify MCP Server

Instructions

Implementation Reference

• src/spotify.ts:694-705 (handler)

  Core handler implementation in SpotifyService that clamps the volume percent to 0-100 and makes a PUT request to Spotify API endpoint /me/player/volume?volume_percent={volume}[&device_id={deviceId}] to set the volume on the specified or active device.

  async setVolume(
    token: string,
    volumePercent: number,
    deviceId: string | null = null
  ): Promise<void> {
    const volume = Math.min(Math.max(volumePercent, 0), 100);
    let endpoint = `me/player/volume?volume_percent=${volume}`;
    if (deviceId) {
      endpoint += `&device_id=${deviceId}`;
    }
    return await this.makeRequest<void>(endpoint, token, {}, "PUT");
  }

• src/mcp/tools/playback.ts:297-341 (registration)

  MCP tool registration for 'set_volume' including title, description, input schema, and handler that delegates to SpotifyService.setVolume.

    set_volume: {
      title: "Set Player Volume",
      description: `Adjust the volume level for the user's active Spotify device.
  
  🎯 USE CASES:
  • Create dynamic volume adjustments for different times of day
  • Build smart home automation with volume control
  • Implement voice commands for hands-free volume changes
  • Adjust volume based on ambient noise levels
  • Create custom audio experience controls
  
  📝 WHAT IT RETURNS:
  • Confirmation of successful volume change
  • Current volume level after adjustment
  • Device information showing updated state
  • Previous volume level for potential undo functionality
  • Playback state with new volume settings
  
  🔍 EXAMPLES:
  • "Set volume to 50%"
  • "Lower the volume to 25"
  • "Turn up the music to 80%"
  • "Make it quieter, set to 15%"
  
  🔊 VOLUME CONTROL:
  • Range: 0-100 percent
  • 0 = Complete silence (muted)
  • 100 = Maximum device volume
  • Changes apply instantly during playback
  • Preserves volume setting for future sessions
  
  ⚠️ REQUIREMENTS:
  • Valid Spotify access token with user-modify-playback-state scope
  • Active device that supports volume control
  • Device must be currently available and responsive`,
      schema: createSchema({
        token: commonSchemas.token(),
        volume_percent: commonSchemas.volumePercent(),
        deviceId: commonSchemas.deviceId(),
      }),
      handler: async (args: any, spotifyService: SpotifyService) => {
        const { token, volume_percent, deviceId } = args;
        return await spotifyService.setVolume(token, volume_percent, deviceId);
      },
    },

• src/mcp/tools/playback.ts:333-336 (schema)

  Input schema definition for the set_volume tool using Zod validation for token, volume_percent (0-100), and optional deviceId.

    token: commonSchemas.token(),
    volume_percent: commonSchemas.volumePercent(),
    deviceId: commonSchemas.deviceId(),
  }),

• src/mcp/schemas/common.ts:57-58 (schema)

  Reusable Zod schema helper for volume_percent parameter, enforcing 0-100 integer range with description.

  volumePercent: () =>
    z.number().min(0).max(100).describe("Volume level as a percentage (0-100)"),