How to connect Sonos MCP with TypeScript

Get the household, group, and player IDs every other Sonos tool needs — a discovery of the user's whole Sonos system(s): every household, its groups (each with current playback state), and their players (speakers) with capabilities. Call it the first time you need any ID, and again after any grouping change (add_players_to_group, remove_players_from_group, move_audio_to_players), since group IDs and memberships go stale. Otherwise reuse that result for the rest of the conversation — no need to call it again before every operation. Only a call made in the current conversation is authoritative — never rely on names or IDs from any other source (your memory, past conversations, or general knowledge of the setup), because the system can change anytime (players renamed, groups reorganized, added, or removed).

Return what's currently playing on a Sonos group: the source (playlist, station, album, or radio, with its name and type); the current song or track's name, artist, album, and duration — or, for radio and other streams, the station or stream info; and the next track when available. Playback advances continuously — call this every time the user asks what's playing, even if you called it earlier in the conversation.

Get the shuffle, repeat, and crossfade settings for a Sonos group. Returns shuffle, repeat, repeatOne, and crossfade as booleans.

Change one or more of the shuffle, repeat, and crossfade settings for the content currently playing on a Sonos group: shuffle, repeat, repeat_one, or crossfade. Omit any setting to leave it unchanged; specify at least one. Settings take effect from the next track transition and do not change the currently-playing track. To shuffle content you are about to start, set the shuffle parameter on the play_* tool instead.

Resume playback on a Sonos group — unpause and continue playing. This is the plain 'play'/'resume'/'unpause' action; to start new content, use one of the play_* tools. IMPORTANT: Stateless command — always execute when asked, without first checking or assuming whether music is playing or paused.

Pause playback on a Sonos group — stop the music where it is (it can be resumed). This is the plain 'pause'/'stop' action. IMPORTANT: Stateless command — always execute when asked, without first checking or assuming whether music is playing or paused.

Skip to the next track on a Sonos group. Use this when the user asks to skip or play the next track.

Skip to the previous track on a Sonos group. Use this when the user asks to go back or play the previous track.

Jump to a specific time in the currently playing track on a Sonos group. Pass position_millis for an absolute target, or delta_millis to fast forward (positive) or rewind (negative) from the current position.

Get the volume and mute state of a Sonos player. Group volume and player volume are linked — changing one affects the other. To get the volume of a whole group, use get_group_volume instead.

Set the volume of a Sonos player to a specific level. Setting a player's volume does not change its mute state. Group volume and player volume are linked — changing one affects the other. To set the volume of a whole group proportionally, use set_group_volume instead.

Mute or unmute a Sonos player. Group volume and player volume are linked — changing one affects the other. To mute all players in a group, use set_group_mute instead.

Turn a Sonos player's volume up or down by the specified amount. Adjusting a player's volume does not change its mute state. Group volume and player volume are linked — changing one affects the other. To turn a whole group up or down proportionally, use adjust_group_volume instead.

Get the volume and mute state of a Sonos group. Group volume is the average level across the group's players. Group volume and player volume are linked — changing one affects the other. To get the volume of a single player, use get_player_volume instead.

Set the volume of a Sonos group to a specific level. Scales all players in the group proportionally, preserving their relative balance — it does not set every player to the same level. If the group is muted (all its players muted), setting the group volume also unmutes it. Group volume and player volume are linked — changing one affects the other. To set the volume of a single player, use set_player_volume; to set every player to an identical level, call it on each player individually instead.

Mute or unmute all players in a Sonos group. Group volume and player volume are linked — changing one affects the other. To mute a single player, use set_player_mute instead.

Turn a Sonos group's volume up or down by the specified amount. Adjusts all players in the group proportionally, preserving their relative balance — it does not apply the same delta to every player. If the group is muted (all its players muted), adjusting the group volume also unmutes it. Group volume and player volume are linked — changing one affects the other. To turn a single player up or down, use adjust_player_volume; to apply an identical delta to every player, call it on each player individually instead.

Get all Sonos favorites saved to a Sonos household. These are items saved within the Sonos app and are distinct from favorites or saved content on any music service. Returns each favorite's name and ID. Use this when the user asks what Sonos favorites are available, or to look up a favorite ID before playing one. Favorites marked `unavailable: true` can't be played — likely the associated music service account is missing.

Get all Sonos playlists saved to a Sonos household. These are playlists created in or imported into the Sonos app and are distinct from playlists on any music service. Returns each playlist's name, ID, and track count. Use this when the user asks what Sonos playlists are available, or to look up a playlist ID before playing one.

Play a Sonos playlist on a group. Use get_sonos_playlists first to find the playlist ID. For music service playlists use play_playlist instead.

Play a Sonos favorite on a group. Use get_sonos_favorites first to find the favorite ID.

Play the line-in audio from one Sonos player on a group. Use this when the user wants an external audio source (turntable, record player, CD player, etc.) connected to a player's line-in jack to play on a group — e.g., 'play the kitchen's line-in in the bedroom'. The source player must have a line-in jack — check that `LINE_IN` is in its capabilities from get_households_and_groups_and_players.

List the music services the user has set up for a Sonos household. Call this only to answer informational queries like 'what music services are set up on Sonos?' The accountLabel is a user-defined label for disambiguating multiple accounts of the same service; it defaults to the account name but can be any string.

Add players to a Sonos group. The added players adopt the group's current audio (replacing whatever they were previously playing). Use this for requests like 'add the bedroom to the group' or 'also play in the kitchen'. Also use this before starting multi-player playback ('play X in both the kitchen and bedroom') — group the players first, then call a play_* tool on the combined group so all players play in sync. All players must belong to the same household as the group. IMPORTANT: After this call, always call get_households_and_groups_and_players once before continuing — group IDs and memberships from earlier in the conversation may be invalid (groups can be created, disbanded, or recomposed; player IDs stay stable). Don't reason about what changed; use the fresh state.

Remove players from a Sonos group. The removed players stop playing (their previous audio does not resume); the rest of the group continues uninterrupted. Use this for requests like 'remove the bedroom from the group' or 'ungroup the kitchen'. All players must belong to the same household as the group. IMPORTANT: After this call, always call get_households_and_groups_and_players once before continuing — group IDs and memberships from earlier in the conversation may be invalid (groups can be created, disbanded, or recomposed; player IDs stay stable). Don't reason about what changed; use the fresh state.

Move the audio currently playing on a Sonos group to a new set of players, atomically and with no audio gap. Players in the source group not listed in destination_player_ids stop playing (their previous audio does not resume); players in destination_player_ids that weren't in the source group adopt the moved audio. Use this for requests like 'move the music from the kitchen to the bedroom', 'switch playback to the kitchen instead', or 'play in the bedroom only'. To simply add players to a group, use add_players_to_group; to simply remove, use remove_players_from_group. All players must belong to the same household as the group. IMPORTANT: After this call, always call get_households_and_groups_and_players once before continuing — group IDs and memberships from earlier in the conversation may be invalid (groups can be created, disbanded, or recomposed; player IDs stay stable). Don't reason about what changed; use the fresh state.

Get the Night Sound and Speech Enhancement settings for a Sonos player. Speech Enhancement improves TV dialogue and voice clarity; Night Sound reduces loud effects for late-night listening. Only supported on players with home theater playback (soundbars) — check that `HT_PLAYBACK` is in their capabilities from get_households_and_groups_and_players. Returns nightSound and speechEnhancement as booleans.

Set Night Sound and Speech Enhancement for a Sonos player. Speech Enhancement improves TV dialogue and voice clarity; Night Sound reduces loud effects for late-night listening. Only supported on players with home theater playback (soundbars) — check that `HT_PLAYBACK` is in their capabilities from get_households_and_groups_and_players. Omit any setting to leave it unchanged; specify at least one.

Play a track on a Sonos group.

Play an album on a Sonos group.

Play a mix of music from an artist on a Sonos group.

Play a playlist from a music service on a Sonos group. For Sonos playlists, use play_sonos_playlist instead.

Play a live broadcast radio station on a Sonos group — a specific, named station the user tunes into, heard as a single continuous stream everyone gets in sync and can't skip. Covers over-the-air and internet broadcasts (BBC Radio 1, NPR, KEXP, 98.5 FM), streaming-native broadcast channels (Apple Music 1, Apple Music Hits), and hosted Sonos Radio shows ('Sunset Fuzz', 'Nashville Now'). Identify it by station or show name, call sign, or frequency — pass at least one of radio_name, call_sign, or frequency; add location only to disambiguate same-named stations. Use play_station instead for an endless station generated from a seed rather than identified by name.

Play a personalized, endless station generated from a seed on a Sonos group — something a music service turns into an algorithmic run of tracks (e.g. 'Daft Punk Radio', 'jazz station', 'a chill station', 'Bohemian Rhapsody radio'). Seed it with exactly one of station_name, artist, or track (whichever the user names). Use play_radio instead for a live broadcast station or a hosted Sonos Radio show ('Sunset Fuzz', 'Nashville Now') identified by name rather than generated from a seed.