adjustVolume
Control Spotify playback volume by increasing or decreasing levels using positive or negative values. Requires Spotify Premium subscription.
Instructions
Adjust the playback volume up or down by a relative amount. Use positive values to increase, negative to decrease. Requires Spotify Premium.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adjustment | Yes | The amount to adjust volume by (-100 to 100). Positive increases, negative decreases. | |
| deviceId | No | The Spotify device ID to adjust volume on |
Implementation Reference
- src/play.ts:434-497 (handler)Handler function that retrieves current playback state, calculates new volume by adding the adjustment (clamped between 0-100), sets the volume using Spotify API, and returns a success message.
handler: async (args, _extra: SpotifyHandlerExtra) => { const { adjustment, deviceId } = args; try { // First get the current playback state to find current volume const playback = await handleSpotifyRequest(async (spotifyApi) => { return await spotifyApi.player.getPlaybackState(); }); if (!playback?.device) { return { content: [ { type: 'text', text: 'No active device found. Make sure Spotify is open and playing on a device.', }, ], }; } const currentVolume = playback.device.volume_percent; if (currentVolume === null || currentVolume === undefined) { return { content: [ { type: 'text', text: 'Unable to get current volume from device.', }, ], }; } const newVolume = Math.min(100, Math.max(0, currentVolume + adjustment)); await handleSpotifyRequest(async (spotifyApi) => { await spotifyApi.player.setPlaybackVolume( Math.round(newVolume), deviceId || '', ); }); const direction = adjustment > 0 ? 'increased' : 'decreased'; return { content: [ { type: 'text', text: `Volume ${direction} from ${currentVolume}% to ${Math.round(newVolume)}%`, }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error adjusting volume: ${ error instanceof Error ? error.message : String(error) }`, }, ], }; } }, }; - src/play.ts:421-433 (schema)Input schema using Zod: 'adjustment' (number between -100 and 100), optional 'deviceId' (string).
schema: { adjustment: z .number() .min(-100) .max(100) .describe( 'The amount to adjust volume by (-100 to 100). Positive increases, negative decreases.', ), deviceId: z .string() .optional() .describe('The Spotify device ID to adjust volume on'), }, - src/play.ts:499-510 (registration)The adjustVolume tool is included in the exported playTools array.
export const playTools = [ playMusic, pausePlayback, skipToNext, skipToPrevious, createPlaylist, addTracksToPlaylist, resumePlayback, addToQueue, setVolume, adjustVolume, ]; - src/index.ts:12-14 (registration)playTools array (including adjustVolume) is spread and each tool is registered with the MCP server via server.tool().
[...readTools, ...playTools, ...albumTools].forEach((tool) => { server.tool(tool.name, tool.description, tool.schema, tool.handler); });