Tommertom/sonos-ts-mcp

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.
📚 Documentation
- **Comprehensive Tool Descriptions** - Detailed guide for coding agents with use cases, workflows, and best practices for all 50+ tools
- **API Reference** - Technical API documentation
- **Example Scripts** - Sample automation scripts and use cases
Getting Started
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:
Basic Configuration
Claude Desktop
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.
Cline
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.
Cursor
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):
Visual Studio Code Copilot
To configure a single project, edit the .vscode/mcp.json file in your workspace:
To make the server available in every project you open, edit your user settings:
Windsurf Editor
To configure Windsurf Editor, edit the file ~/.codeium/windsurf/mcp_config.json:
Testing with an Agent
You can quickly test the MCP server using the built-in CLI agent, which uses natural language to interact with your Sonos system:
**Required Environment Variables:**
- OPENAI_API_KEY: For OpenAI models (gpt-4o, gpt-4o-mini, etc.)
- GOOGLE_GENERATIVE_AI_API_KEY: For Gemini models
- SONOS_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:
This agent provides an easy way to verify that the MCP server is working correctly and can communicate with your Sonos devices.
Features
This MCP server provides comprehensive control of your Sonos audio system:
- **AI-Powered Agent Tool**: Natural language control via the sonos_agent tool (requires AI API keys) ✨ NEW
- **Topology Persistence**: Device topology automatically saved to disk and loaded on startup
- **Intelligent Device Resolution**: Control devices by friendly name (e.g., "Kitchen") instead of UUIDs
- **Automatic Discovery**: Discovers devices on startup and every 5 minutes
- **Device Discovery**: Manual SSDP-based discovery of Sonos devices
- **Playback Control**: Play, pause, stop, next, previous
- **Volume Control**: Get and set volume levels, mute/unmute
- **Transport Info**: Get current playback state and track information
- **Zone Topology**: Query zone groups and speaker configurations
- **Queue Management**: Full queue control (add, remove, reorder, save, play)
- **DIDL-Lite Support**: Complete metadata handling for tracks, albums, and containers