set_volume
Adjust the volume level on your active Spotify device by setting a percentage from 0 to 100, enabling precise audio control during playback.
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 |
|---|---|---|---|
| token | Yes | Spotify access token for authentication | |
| volume_percent | Yes | Volume level as a percentage (0-100) | |
| deviceId | No | Spotify device ID (optional, uses active device if not specified) |
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)"),