set_volume
Adjust Spotify playback volume on active devices using a percentage scale (0-100). Enables dynamic volume changes, smart home integration, and hands-free control for custom audio experiences.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | No | Spotify device ID (optional, uses active device if not specified) | |
| token | Yes | Spotify access token for authentication | |
| volume_percent | Yes | Volume level as a percentage (0-100) |
Implementation Reference
- src/mcp/tools/playback.ts:337-340 (handler)Handler function that destructures the input arguments and delegates to SpotifyService.setVolume to adjust the playback volume.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:332-336 (schema)Zod schema definition for set_volume tool inputs: Spotify token, volume percentage (0-100), and optional device ID.schema: createSchema({ token: commonSchemas.token(), volume_percent: commonSchemas.volumePercent(), deviceId: commonSchemas.deviceId(), }),
- src/mcp/tools/index.ts:22-36 (registration)Registration of playbackTools (containing set_volume) into the central allTools registry used by ToolRegistrar for MCP tool exposure.export const allTools: ToolsRegistry = { ...albumTools, ...artistTools, ...trackTools, ...playlistTools, ...playbackTools, ...userTools, ...searchTools, };
- src/spotify.ts:694-705 (helper)SpotifyService helper method that clamps volume to 0-100 and makes PUT request to Spotify API /me/player/volume endpoint.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"); }