Your comprehensive Sonos control companion powered by the Model Context Protocol (MCP). This intelligent server provides seamless access to Sonos audio devices over your local network using UPnP/SOAP protocols. Whether you're controlling playback, managing zones, browsing your music library, or setting up alarms, this MCP server delivers complete device control directly to your AI assistant, enabl
Add this skill
npx mdskills install Tommertom/sonos-ts-mcpComprehensive Sonos control with 50+ tools, excellent docs, and AI agent integration
Your comprehensive Sonos control companion powered by the Model Context Protocol (MCP). This intelligent server provides seamless access to Sonos audio devices over your local network using UPnP/SOAP protocols. Whether you're controlling playback, managing zones, browsing your music library, or setting up alarms, this MCP server delivers complete device control directly to your AI assistant, enabling smart home automation and better audio experiences.
Specifically designed for coding agents and AI-driven home audio automation workflows. This server enables AI assistants to build intelligent multi-room audio experiences, music library management, zone grouping, queue management, and integration with smart home platforms.
Data is sourced from real-time UPnP/SOAP communication with Sonos devices to ensure accuracy and completeness.
📊 Feature Status: Phase 4 complete! Implements real-time event subscriptions with UPnP GENA protocol for playback, volume, queue, and topology changes. See Phase 4 completion for details.
The Sonos TypeScript MCP Server can work with any MCP client that supports standard I/O (stdio) as the transport medium. Here are specific instructions for some popular tools:
To configure Claude Desktop to use the Sonos MCP server, edit the claude_desktop_config.json file. You can open or create this file from the Claude > Settings menu. Select the Developer tab, then click Edit Config.
{
"mcpServers": {
"sonos-ts-mcp": {
"command": "npx",
"args": ["-y", "sonos-ts-mcp@latest"]
}
}
}
To configure Cline to use the Sonos MCP server, edit the cline_mcp_settings.json file. You can open or create this file by clicking the MCP Servers icon at the top of the Cline pane, then clicking the Configure MCP Servers button.
{
"mcpServers": {
"sonos-ts-mcp": {
"command": "npx",
"args": ["-y", "sonos-ts-mcp@latest"],
"disabled": false
}
}
}
To configure Cursor to use the Sonos MCP server, edit either the file .cursor/mcp.json (to configure only a specific project) or the file ~/.cursor/mcp.json (to make the MCP server available in all projects):
{
"mcpServers": {
"sonos-ts-mcp": {
"command": "npx",
"args": ["-y", "sonos-ts-mcp@latest"]
}
}
}
To configure a single project, edit the .vscode/mcp.json file in your workspace:
{
"servers": {
"sonos-ts-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "sonos-ts-mcp@latest"]
}
}
}
To make the server available in every project you open, edit your user settings:
{
"mcp": {
"servers": {
"sonos-ts-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "sonos-ts-mcp@latest"]
}
}
}
}
To configure Windsurf Editor, edit the file ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"sonos-ts-mcp": {
"command": "npx",
"args": ["-y", "sonos-ts-mcp@latest"]
}
}
}
You can quickly test the MCP server using the built-in CLI agent, which uses natural language to interact with your Sonos system:
# Run directly with npx (no installation required)
npx sonos-agent-cli "Play jazz in the living room"
# Use a specific AI model
npx sonos-agent-cli "What's playing in the kitchen?" --model gpt-4o
# Use Gemini models
npx sonos-agent-cli "Set volume to 50 in all rooms" --model gemini-3-pro-preview
Required Environment Variables:
OPENAI_API_KEY: For OpenAI models (gpt-4o, gpt-4o-mini, etc.)GOOGLE_GENERATIVE_AI_API_KEY: For Gemini modelsSONOS_AGENT_MODEL: Set a default model (optional)Build Behavior:
The CLI automatically builds the MCP server before running to ensure the latest code is used. To skip the build (e.g., during rapid testing), use --skip-build:
npx sonos-agent-cli "Play music" --skip-build
This agent provides an easy way to verify that the MCP server is working correctly and can communicate with your Sonos devices.
This MCP server provides comprehensive control of your Sonos audio system:
sonos_agent tool (requires AI API keys) ✨ NEWThis project is actively expanding to match the comprehensive feature set of the Python SoCo library:
See the Phase 4 completion for the latest features.
| Tool | Description |
|---|---|
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 for details. |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
sonos_play | Start playback |
sonos_pause | Pause playback |
sonos_stop | Stop playback |
sonos_next | Skip to next track |
sonos_previous | Skip to previous track |
| Tool | Description |
|---|---|
sonos_set_volume | Set volume (0-100) |
sonos_get_volume | Get current volume |
sonos_set_mute | Mute or unmute |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
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) |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
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) |
| Tool | Description |
|---|---|
sonos_set_sleep_timer | Set automatic playback stop timer |
sonos_get_sleep_timer | Get remaining timer |
sonos_cancel_sleep_timer | Cancel sleep timer |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
sonos_snapshot | Take a snapshot of device state |
sonos_restore_snapshot | Restore from snapshot |
| Tool | Description |
|---|---|
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 |
| Tool | Description |
|---|---|
sonos_get_transport_info | Get playback state |
sonos_get_position_info | Get current track details |
sonos_get_zone_groups | Get zone topology |
npm install
npm run build
After installation, you can test if your Sonos devices can be discovered:
npm run test:discovery
This will perform an SSDP multicast search and display any Sonos devices found on your network.
You can test the favorite radio stations feature:
npm run test:radio
This will query your Sonos device for saved radio stations and display them. If no stations are found, it will provide instructions on how to add some using the Sonos app.
You can test the AI-powered agent tool (requires AI API keys):
# Set up your API key first
export OPENAI_API_KEY=sk-...
# or
export GOOGLE_GENERATIVE_AI_API_KEY=...
# Run the test
npm run test:agent-tool
This will verify that the agent tool is properly configured and can execute natural language instructions. See the Agent Tool Documentation for more details.
The server supports two transport modes:
Stdio mode is the standard way to run MCP servers, communicating over standard input/output. This is the mode used by most MCP clients.
Add to your MCP client configuration:
{
"mcpServers": {
"sonos": {
"command": "node",
"args": ["path/to/sonos-ts-mcp/dist/index.js"]
}
}
}
Or run directly:
node dist/index.js
You can also use the convenience script:
npm run start:stdio
# or
tsx scripts/start-mcp-stdio.ts
The project includes a CLI agent powered by Mastra that allows you to control your Sonos system using natural language.
# Run with default model (gpt-4o-mini)
npx sonos-agent-cli "Play jazz in the living room"
# Run with a specific model
npx sonos-agent-cli "Play jazz in the living room" --model gpt-4o
# Run with Gemini 3
npx sonos-agent-cli "Play jazz in the living room" --model gemini-3-pro-preview
Environment Variables:
OPENAI_API_KEY: Required for OpenAI models (default)GOOGLE_GENERATIVE_AI_API_KEY: Required for Gemini modelsSONOS_AGENT_MODEL: Set the default model (optional, e.g., gemini-3-pro-preview)Note on Telemetry: The Mastra framework's built-in telemetry has been disabled in this implementation. Telemetry warnings are suppressed by setting globalThis.___MASTRA_TELEMETRY___ = true before Mastra initialization. This is set automatically in the CLI agent.
SSE (Server-Sent Events) mode runs the MCP server as an HTTP server, useful for web-based clients or remote access.
Set the MCP_TRANSPORT environment variable to sse:
MCP_TRANSPORT=sse node dist/index.js
Or with custom port (default is 3000):
MCP_TRANSPORT=sse MCP_PORT=8080 node dist/index.js
You can also use the convenience script:
npm run start:sse
# or
tsx scripts/start-mcp-sse.ts
With custom port:
MCP_PORT=8080 npm run start:sse
The server will start an HTTP endpoint at http://localhost:3000/sse (or your configured port) that clients can connect to.
npm run dev # Run with tsx (hot reload)
npm run build # Compile TypeScript
npm run typecheck # Type checking only
npm run lint # ESLint
npm run format # Prettier
npm test # Run tests
npm run test:discovery # Test Sonos device discovery
npm run test:phase1 # Test Phase 1 APIs (Queue, Playback)
npm run test:phase2 # Test Phase 2 APIs (Groups, Library)
npm run test:phase3 # Test Phase 3 APIs (Audio, Alarms)
npm run test:phase4 # Test Phase 4 APIs (Events)
npm run test:all-phases # Run all phase tests
Comprehensive API test scripts are available for all implemented features:
# Run all tests
npm run test:all-phases
# Or run individual phase tests
npm run test:phase1 # Queue, DIDL, Playback Properties
npm run test:phase2 # Groups & Music Library Browsing
npm run test:phase3 # Audio, Alarms, Snapshots
npm run test:phase4 # Event Subscriptions
# Run Phase 2 tests in mock mode (no physical devices required)
npm run test:phase2 -- --mock
# Run integration tests (uses AI validation)
npm test
Note: Phase 2 tests support a mock mode for testing without physical Sonos devices. Use --mock flag or set MOCK_DEVICES=true environment variable.
AI-Powered Integration Tests: The integration test suite uses Gemini 2.5 Flash AI to intelligently validate agent outputs instead of brittle string matching. This provides semantic understanding of test results and adapts to different output formats. Requires GOOGLE_GENERATIVE_AI_API_KEY environment variable.
See the API Testing Guide and AI-Powered Testing Guide for detailed documentation on the test suite.
src/
├── discovery/ # SSDP device discovery
│ ├── ssdp-client.ts
│ └── device-registry.ts
├── didl/ # DIDL-Lite metadata handling
│ ├── didl-object.ts
│ ├── didl-resource.ts
│ ├── didl-item.ts
│ ├── didl-container.ts
│ ├── didl-serializer.ts
│ ├── didl-parser.ts
│ └── index.ts
├── soap/ # SOAP/UPnP transport layer
│ ├── client.ts
│ ├── request-builder.ts
│ └── response-parser.ts
├── services/ # Sonos service wrappers
│ ├── base-service.ts
│ ├── av-transport.ts # Playback, queue, sleep timer
│ ├── rendering-control.ts # Volume, EQ, audio enhancements
│ ├── zone-topology.ts # Groups, party mode
│ ├── content-directory.ts # Music library browsing
│ ├── alarm-clock.ts # ✨ NEW: Alarm management
│ └── snapshot.ts # ✨ NEW: State snapshot/restore
├── mcp/ # MCP server implementation
│ └── server.ts
└── types/ # TypeScript definitions
├── sonos.ts
└── queue.ts
239.255.255.250:1900urn:schemas-upnp-org:device:ZonePlayer:1Note on Discovery: SSDP multicast discovery may not work in all network environments due to:
If automatic discovery fails, use the sonos_add_device tool to manually register devices by IP address. The server will verify connectivity before registering the device.
When SSDP discovery doesn't work, you can manually add devices:
// Using the MCP tool
sonos_add_device({
ip: "192.168.1.100",
port: 1400, // optional, defaults to 1400
name: "Kitchen" // optional, defaults to "Sonos at {ip}"
})
The server will test connectivity to the device before adding it to the registry.
http://{ip}:1400/...Contributions are welcome! This project is expanding to provide comprehensive Sonos control. See the roadmap for planned features.
Areas where contributions are especially valuable:
MIT
Install via CLI
npx mdskills install Tommertom/sonos-ts-mcpSonos TypeScript MCP Server is a free, open-source AI agent skill. Your comprehensive Sonos control companion powered by the Model Context Protocol (MCP). This intelligent server provides seamless access to Sonos audio devices over your local network using UPnP/SOAP protocols. Whether you're controlling playback, managing zones, browsing your music library, or setting up alarms, this MCP server delivers complete device control directly to your AI assistant, enabl
Install Sonos TypeScript MCP Server with a single command:
npx mdskills install Tommertom/sonos-ts-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
Sonos TypeScript MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.