# Sonos Mcp Server

> MCP server for controlling Sonos speakers - playback, volume, groups, queue, playlists and favourites via Claude Desktop (or other MCP supported LLM's)

- **Type:** MCP server
- **Install:** `agentstack add mcp-paulknauer-sonos-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PaulKnauer](https://agentstack.voostack.com/s/paulknauer)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [PaulKnauer](https://github.com/PaulKnauer)
- **Source:** https://github.com/PaulKnauer/sonos-mcp-server

## Install

```sh
agentstack add mcp-paulknauer-sonos-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SoniqMCP — Sonos MCP Server

Control your Sonos system from any MCP-compatible AI client. Run locally over stdio, deploy with Docker on Linux for whole-home access, or follow the documented Helm / k3s guidance when its networking caveats fit your environment.

## What it does

SoniqMCP is an [MCP](https://modelcontextprotocol.io/) server that exposes your Sonos system as tools for AI agents. Connect Claude Desktop (or any MCP client) to control playback, volume, queues, favourites, playlists, local music library browsing and playback, and room grouping through natural conversation.

**Tools available:**

| Category | Tools |
|---|---|
| System | `list_rooms`, `get_system_topology` |
| Playback | `play`, `pause`, `stop`, `next_track`, `previous_track`, `get_playback_state`, `get_track_info` |
| Playback Modes | `get_play_mode`, `set_play_mode`, `seek`, `get_sleep_timer`, `set_sleep_timer` |
| Volume | `get_volume`, `set_volume`, `adjust_volume`, `mute`, `unmute`, `get_mute` |
| Room Audio | `get_eq_settings`, `set_bass`, `set_treble`, `set_loudness` |
| Queue | `get_queue`, `add_to_queue`, `remove_from_queue`, `clear_queue`, `play_from_queue` |
| Favourites | `list_favourites`, `play_favourite` |
| Alarm Lifecycle | `list_alarms`, `create_alarm`, `update_alarm`, `delete_alarm` |
| Playlist Playback and Lifecycle | `list_playlists`, `play_playlist`, `create_playlist`, `update_playlist`, `delete_playlist` |
| Local Music Library | `browse_library`, `play_library_item` |
| Groups | `get_group_topology`, `join_group`, `unjoin_room`, `party_mode`, `group_rooms` |
| Group Audio | `get_group_volume`, `set_group_volume`, `adjust_group_volume`, `group_mute`, `group_unmute` |
| Inputs | `switch_to_line_in`, `switch_to_tv` |
| Setup | `ping`, `server_info` |

## Quick start

**Prerequisites:** Python 3.12+, [uv](https://docs.astral.sh/uv/)

```bash
# 1. Clone and install
git clone  sonos-mcp-server
cd sonos-mcp-server
make install        # runs: uv sync

# 2. Configure (copy and edit)
cp .env.example .env

# 3. Run
make run            # starts the server over stdio
```

See [docs/setup/stdio.md](docs/setup/stdio.md) for the full local setup guide including Claude Desktop wiring. After the server is running, use [docs/prompts/example-uses.md](docs/prompts/example-uses.md) for direct and agent-mediated prompt examples, and use [docs/prompts/command-reference.md](docs/prompts/command-reference.md) as the canonical command surface.

## Deployment models

| | Local stdio | Docker (HTTP) | Helm / k3s (HTTP) |
|---|---|---|---|
| Best for | Same-machine AI client | Linux home-lab server | Self-hosted k3s/Kubernetes |
| Client location | Same machine only | Any network client | Any network client |

See [docs/setup/README.md](docs/setup/README.md) for the full deployment comparison and setup guides.

## Configuration

All configuration is via a project-local `.env` file or environment variables.
When both are present, environment variables win:

| Variable | Default | Description |
|---|---|---|
| `SONIQ_MCP_TRANSPORT` | `stdio` | Transport mode (`stdio` or `http`) |
| `SONIQ_MCP_EXPOSURE` | `local` | Network exposure posture (`local` or `home-network`) |
| `SONIQ_MCP_LOG_LEVEL` | `INFO` | Log level (DEBUG/INFO/WARNING/ERROR) |
| `SONIQ_MCP_DEFAULT_ROOM` | _(none)_ | Optional default Sonos room |
| `SONIQ_MCP_MAX_VOLUME_PCT` | `80` | Volume safety cap (0–100) |
| `SONIQ_MCP_TOOLS_DISABLED` | _(none)_ | Comma-separated tools to disable |
| `SONIQ_MCP_HTTP_HOST` | `127.0.0.1` | Bind address (HTTP transport only; for home-network access, also set `SONIQ_MCP_EXPOSURE=home-network` and use `0.0.0.0` or a LAN address) |
| `SONIQ_MCP_HTTP_PORT` | `8000` | Port (HTTP transport only) |
| `SONIQ_MCP_AUTH_MODE` | `none` | HTTP auth mode: `none`, `static`, or `oidc` (HTTP transport only) |

For static and OIDC auth configuration, see [docs/setup/authentication.md](docs/setup/authentication.md).

## Command surface

The supported command surface lives in [docs/prompts/command-reference.md](docs/prompts/command-reference.md). That page is the canonical reference for:

- `make` targets for development, quality gates, Docker, Compose, and Helm
- direct CLI invocation examples
- the relationship between local `stdio` workflows and remote `Streamable HTTP` deployment paths

## Docs

- [Setup overview and deployment models](docs/setup/README.md)
- [Local stdio setup guide](docs/setup/stdio.md)
- [Docker deployment guide](docs/setup/docker.md)
- [Helm deployment guide](docs/setup/helm.md)
- [Authentication guide](docs/setup/authentication.md)
- [Troubleshooting](docs/setup/troubleshooting.md)
- [Operations and release guidance](docs/setup/operations.md)
- [Prompts and command reference index](docs/prompts/README.md)
- [Example prompts and usage flows](docs/prompts/example-uses.md)
- [Command reference](docs/prompts/command-reference.md)
- [Claude Desktop integration](docs/integrations/claude-desktop.md)
- [Home Assistant integration](docs/integrations/home-assistant.md)
- [n8n integration](docs/integrations/n8n.md)
- [Security policy](SECURITY.md)
- [Threat model](docs/security/threat-model.md)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PaulKnauer](https://github.com/PaulKnauer)
- **Source:** [PaulKnauer/sonos-mcp-server](https://github.com/PaulKnauer/sonos-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-paulknauer-sonos-mcp-server
- Seller: https://agentstack.voostack.com/s/paulknauer
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.