# Tommertom/sonos-ts-mcp [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/Tommertom/sonos-ts-mcp  
**GitHub Stars:** 15  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tommertom-sonos-ts-mcp

## Description
Comprehensive Sonos audio system control through pure TypeScript implementation. Features complete device discovery, multi-room playback management, queue control, music library browsing, alarm management, real-time event subscriptions, and audio EQ settings. Includes 50+ tools for seamless smart home audio automation via UPnP/SOAP protocols.

## Tools
Capabilities this server exposes over MCP:

- **sonos_agent** — AI-powered natural language control. Give instructions like "Play jazz in the living room" and the agent autonomously handles device discovery, tool selection, and execution. Only available when `OPENAI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` is configured. See [Agent Tool Documentation](./docs/…
- **sonos_discover** — Discover Sonos devices on the network using SSDP multicast
- **sonos_add_device** — Manually add a Sonos device by IP address (useful when SSDP discovery fails)
- **sonos_list_devices** — List all discovered/registered devices
- **sonos_play** — Start playback
- **sonos_pause** — Pause playback
- **sonos_stop** — Stop playback
- **sonos_next** — Skip to next track
- **sonos_previous** — Skip to previous track
- **sonos_set_volume** — Set volume (0-100)
- **sonos_get_volume** — Get current volume
- **sonos_set_mute** — Mute or unmute
- **sonos_get_queue** — Get the current playback queue
- **sonos_add_to_queue** — Add a URI to the queue
- **sonos_remove_from_queue** — Remove a track from the queue
- **sonos_clear_queue** — Remove all tracks from the queue
- **sonos_play_from_queue** — Play from a specific queue position
- **sonos_save_queue** — Save the queue as a Sonos playlist
- **sonos_set_shuffle** — Enable or disable shuffle mode
- **sonos_set_repeat** — Set repeat mode (off, all, one)
- **sonos_set_crossfade** — Enable or disable crossfade
- **sonos_get_playback_state** — Get shuffle, repeat, crossfade, and playback state
- **sonos_join_group** — Join a device to another device's group
- **sonos_unjoin** — Remove a device from its group
- **sonos_party_mode** — Join all devices at once
- **sonos_browse_artists** — Browse all artists in the music library
- **sonos_browse_albums** — Browse all albums in the music library
- **sonos_browse_tracks** — Browse all tracks in the music library
- **sonos_browse_genres** — Browse all genres in the music library
- **sonos_browse_playlists** — Browse Sonos playlists
- **sonos_get_favorite_radio_stations** — Get favorite radio stations from Sonos favorites
- **sonos_search_library** — Search the music library
- **sonos_browse_item** — Browse subcategories (e.g., albums for an artist)
- **sonos_list_music_services** — List available music services (Sonos Radio, TuneIn, Spotify, etc.)
- **sonos_browse_music_service** — Browse content from a music service (categories, stations, playlists)
- **sonos_search_music_service** — Search for content within a music service
- **sonos_play_music_service_item** — Play an item from a music service (radio station, track, album)
- **sonos_get_music_service_item_uri** — Get the streaming URI for a music service item
- **sonos_set_bass** — Set bass level (-10 to 10)
- **sonos_set_treble** — Set treble level (-10 to 10)
- **sonos_set_loudness** — Enable/disable loudness compensation
- **sonos_get_eq** — Get all EQ settings
- **sonos_set_night_mode** — Enable/disable night mode (home theater)
- **sonos_set_dialog_mode** — Enable/disable dialog enhancement (home theater)
- **sonos_set_sleep_timer** — Set automatic playback stop timer
- **sonos_get_sleep_timer** — Get remaining timer
- **sonos_cancel_sleep_timer** — Cancel sleep timer
- **sonos_list_alarms** — List all alarms
- **sonos_create_alarm** — Create a new alarm
- **sonos_update_alarm** — Update an existing alarm
- **sonos_delete_alarm** — Delete an alarm
- **sonos_snapshot** — Take a snapshot of device state
- **sonos_restore_snapshot** — Restore from snapshot
- **sonos_subscribe_events** — Subscribe to real-time device events (AVTransport, RenderingControl, Queue, ZoneGroupTopology, AlarmClock)
- **sonos_unsubscribe_events** — Unsubscribe from a specific subscription
- **sonos_unsubscribe_all** — Unsubscribe from all device subscriptions
- **sonos_list_subscriptions** — List active event subscriptions
- **sonos_get_transport_info** — Get playback state
- **sonos_get_position_info** — Get current track details
- **sonos_get_zone_groups** — Get zone topology

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "sonos-ts-mcp": {
    "command": "npx",
    "args": ["-y","sonos-agent-cli"]
  }
}
```

## Documentation

## What Tommertom/sonos-ts-mcp MCP server does

The Tommertom/sonos-ts-mcp MCP server gives MCP-compatible clients access to Sonos systems on a local network. It is implemented in TypeScript and communicates directly with Sonos devices through UPnP and SOAP rather than depending on an external Sonos library.

Its tools cover the main operational areas of a Sonos installation:

- Discovering devices with SSDP, listing registered devices, and adding a device by IP address when discovery does not work.
- Starting, pausing, stopping, and navigating playback.
- Reading and changing volume, mute state, shuffle, repeat, and crossfade settings.
- Reading, modifying, clearing, saving, and playing from queues.
- Joining and unjoining speakers, or placing all available devices into a party group.
- Browsing artists, albums, tracks, genres, and playlists in the Sonos music library.

The repository also describes support for alarms, sleep timers, audio and EQ controls, snapshots and restoration, fuzzy library search, and real-time notifications for playback, volume, queue, and topology changes.

## How it works

The server runs locally and uses standard MCP stdio transport. Sonos devices are located through SSDP multicast, with manual IP registration available as a fallback. Device topology is persisted to disk and loaded when the process starts; discovery also runs automatically at startup and periodically afterward.

Tools can resolve devices by friendly names such as a room name instead of requiring a UUID. UPnP GENA event subscriptions provide updates when supported Sonos state changes occur. The server exposes MCP prompts as well as tools for clients that support them.

The optional `sonos_agent` tool accepts natural-language requests, selects the relevant Sonos operations, and executes them. That tool is enabled only when `OPENAI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` is configured, so ordinary device-control tools do not require those provider credentials.

## Setup and configuration

Install the Tommertom/sonos-ts-mcp MCP server through npm and register it as a stdio server in the MCP client. The repository provides configurations for Claude Desktop, Cline, Cursor, Windsurf, and Visual Studio Code Copilot. The core configuration uses `npx -y sonos-ts-mcp@latest`.

The client process must be able to reach the Sonos speakers on the same local network or on a network that permits the required discovery and device traffic. If multicast discovery is unavailable, use the manual device-add tool with a speaker IP address.

The natural-language agent has separate model configuration. `OPENAI_API_KEY` enables OpenAI models, `GOOGLE_GENERATIVE_AI_API_KEY` enables Gemini models, and `SONOS_AGENT_MODEL` can select a default model. These settings apply to the agent feature, not to basic Sonos controls.

## Tools and capabilities

The published tool set includes more than 50 operations. Representative groups include:

- Discovery: `sonos_discover`, `sonos_add_device`, and `sonos_list_devices`.
- Playback: play, pause, stop, next, previous, volume, mute, and playback-state operations.
- Queue control: inspect, add, remove, clear, save, and start from a queue position.
- Group control: join, unjoin, and party mode.
- Library access: browse artists, albums, tracks, genres, and playlists.
- Higher-level control: the optional `sonos_agent` natural-language tool.

These capabilities fit room-based playback automation, multi-room synchronization, queue workflows, and assistant-driven audio status checks.

## Limitations and notes

The server depends on local network access to Sonos devices and on UPnP/SOAP communication. SSDP discovery may fail on networks that block multicast; manual IP registration is provided for that case.

Music-service integrations such as Spotify and Apple Music are listed as planned work rather than current functionality. Advanced group features, audio diagnostics, and MCP event-tool integration are also listed for later phases. The natural-language agent additionally depends on a supported external AI provider key, while direct Sonos tools do not.

_Full upstream README: https://allmcps.com/mcp/tommertom-sonos-ts-mcp/readme_