Sonos

Provides MCP-based control of Sonos devices, including discovery, playback, state retrieval, and queue management.

python

5

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "winstonfassett-sonos-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "mcp",
        "run",
        "server.py"
      ]
    }
  }
}

You can run a dedicated MCP server to control and monitor Sonos devices on your network. It exposes a set of practical tools to discover devices, view states, control playback, manage queues, and adjust volume, making it straightforward to integrate Sonos control into MCP-enabled clients and automations.

How to use

You interact with the Sonos MCP Server through MCP clients by invoking its exposed tools. Typical workflows include discovering Sonos devices on your network, checking current playback states, fetching queue information, and issuing playback commands across one or more devices. You can query what is playing now, adjust volume, skip tracks, or modify queues, all via the available MCP tools.

Key tools you can use include: get_all_device_states to pull state data for all detected devices; now_playing to see currently playing tracks; get_device_state for a single device; playback controls such as pause, stop, play; navigation like next and previous; queue management with get_queue and get_queue_length; and various state modifiers like mode, partymode, volume, and track-level operations like skip, play_index, and remove_index_from_queue. These tools let you monitor and control Sonos devices from your MCP client with straightforward commands.

How to install

Prerequisites you need before starting are Python 3.7 or newer and the uv tool for managing MCP projects.

Clone the project repository and navigate into it.

git clone https://github.com/WinstonFassett/sonos-mcp-server.git
cd sonos-mcp-server

Install the necessary dependencies using the uv tool.

uv sync

Start the server in standardstdio mode so it can be interacted with via MCP clients.

uv run mcp run server.py

If you want to expose the MCP server via SSE (Server-Sent Events) using a gateway, run the gateway command and point it at the standard startup command.

npx -y supergateway --port 8000 --stdio "uv run mcp run server.py"

There is a convenience script to start SSE without typing the gateway command every time.

./npx-serve-sse-8000.sh

If you are developing or debugging, you can run the server in development mode to enable the MCP Inspector.

uv run mcp dev server.py

To use SSE in development mode, run the gateway as shown above and, in a separate terminal, start the inspector tool.

npx @modelcontextprotocol/inspector

Additional notes

The server exposes a set of MCP tools that let you interact with Sonos devices programmatically. Ensure your Sonos devices are discoverable on your network for the discovery features to work.

Tools and capabilities

The MCP tools provide a range of capabilities to observe and control Sonos playback and state, including retrieving device states, getting current tracks, controlling playback, managing queues, and adjusting volume. Use these tools from your MCP client to automate common tasks such as playing a specific track, pausing playback across devices, or updating the queue for a device.

Available tools

get_all_device_states

Retrieve the state information for all discovered Sonos devices.

now_playing

Retrieve information about currently playing tracks on all Sonos devices.

get_device_state

Retrieve the state information for a specific Sonos device.

pause

Pause playback on a Sonos device.

stop

Stop playback on a Sonos device.

play

Resume or start playback on a Sonos device.

get_queue

Get the current playback queue for a Sonos device.

get_queue_length

Return the length of the playback queue for a Sonos device.

mode

Get or set the play mode on a Sonos device.

partymode

Enable party mode on the current Sonos device.

speaker_info

Retrieve speaker details for a Sonos device.

get_current_track_info

Get information about the currently playing track for a device.

volume

Get or set the volume on a Sonos device.

skip

Skip a track in the queue for a Sonos device.

play_index

Play a specific track from the queue by index.

remove_index_from_queue

Remove a track from the queue by its index.