Sonos Ts MCP

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.