How do I use sonora-mcp?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

sonora-mcp

Official

by Sonora-Multiroom

Overview Schema Source Related Servers Discussions Admin

Remote

sonora-mcp

MCP server for the Sonora Multiroom audio system. It exposes the Multiroom Audio Hub API as 32 MCP tools, so any AI assistant that supports MCP can list and control your speakers, groups, inputs and routes over a URL.

Architecture

AI Assistant (Copilot, Claude, etc.)
       │
       ▼  MCP (Streamable HTTP, stateless) at /mcp
┌──────────────────────────┐
│  sonora-mcp              │  port 3001
│  (Go, one static binary) │
└────────────┬─────────────┘
             │  HTTP, via the sonora-cli hub package
             ▼
┌──────────────────────────┐
│  Multiroom Audio Hub API │  e.g. port 8080
└──────────────────────────┘

sonora-mcp keeps no state of its own: every tool call is one request to the hub.

Related MCP server: Talky Talky

Install on a Raspberry Pi

One command on the Pi (64-bit Raspberry Pi OS) installs sonora-mcp as a systemd service:

curl -fsSL https://raw.githubusercontent.com/Sonora-Multiroom/sonora-mcp/main/deploy/pi/install.sh | sudo bash -s -- --hub-url http://localhost:8080

Options go after --hub-url:

Option	Default	Description
`--hub-url <url>`	— (required)	Base URL of the Multiroom Audio Hub
`--port <port>`	`3001`	Port sonora-mcp listens on
`--host <address>`	all addresses	Address to listen on, e.g. `127.0.0.1`
`--version <tag>`	the release the script is pinned to (its `RELEASE_TAG`)	Release to install, e.g. `v1.1.0`

The script downloads the release archive, checks it against the release's checksums.txt, installs /usr/local/bin/sonora-mcp, and writes /etc/default/sonora-mcp and the sonora-mcp.service unit. The service starts at boot and restarts on failure. Re-run the same command with different options to reconfigure or upgrade. You can also copy deploy/pi/install.sh to the Pi and run sudo ./install.sh --hub-url <url>.

systemctl status sonora-mcp
curl localhost:3001/health

Other platforms: download the archive for your OS from Releases and run the binary.

Run

sonora-mcp --multiroom-url http://multiroom.lan:8080

Flag	Required	Default	Description
`--multiroom-url <url>`	yes	—	Base URL of the Multiroom Audio Hub (`http` or `https`)
`--port <port>`	no	`3001`	Port to listen on (1–65535)
`--host <address>`	no	all addresses	Address to listen on: an IP such as `127.0.0.1` or `::1`, or `localhost`
`-h`, `--help`	no	—	Show usage

The server does not start without --multiroom-url. A missing or invalid flag prints the error and usage and exits with status 2; a port that can't be opened exits with status 1. Ctrl+C or SIGTERM stops accepting connections, lets in-flight calls finish (up to 6 s) and exits 0. Each tool call is logged to stderr.

Health check

curl http://localhost:3001/health
# {"status":"ok","server":"sonora-mcp","version":"1.1.0","hub":"reachable"}

/health always answers 200 while the server runs. hub is reachable or unreachable, from one read-only hub request bounded by 2 seconds.

Connect an AI assistant

The MCP endpoint is http://<host>:3001/mcp.

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "sonora-mcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "sonora-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp"
    }
  }
}

MCP Inspector (testing)

npx @modelcontextprotocol/inspector

Connect to http://localhost:3001/mcp with the Streamable HTTP transport.

Tools (32)

Every tool returns structured content (and the same JSON as text). Lists are wrapped in an object, such as {"outputs": [...]}.

Inputs

Tool	Description
`listInputs`	List audio inputs (`includeDisabled` to include disabled ones)
`getInput`	Get one input by ID
`createInput`	Register a new ephemeral input from a stream or file URI (`defaultRouteVolume` for its routes)
`deleteInput`	Delete an ephemeral input (static inputs can't be deleted)
`setInputEnabled`	Enable or disable an input

Outputs

Tool	Description
`listOutputs`	List outputs (speakers or zones; `includeDisabled` to include disabled ones)
`getOutput`	Get one output by ID
`setOutputVolume`	Set an output's volume (0–100)
`setOutputMute`	Mute or unmute an output
`setOutputEnabled`	Enable or disable an output
`stopRoutesForOutput`	Stop everything playing on an output, including group routes that include it

Groups

Tool	Description
`listGroups`	List output groups (`includeDisabled` to include disabled ones)
`getGroup`	Get one group by ID
`setGroupVolume`	Set the volume of every output in a group (0–100)
`setGroupMute`	Mute or unmute a group
`setGroupEnabled`	Enable or disable a group
`stopRoutesForGroup`	Stop everything playing in a group and on its members

Routes

Tool	Description
`listRoutes`	List routes, optionally filtered by `status`, `inputId` and `targetId`
`getRoute`	Get one route by ID
`createRoute`	Play an input to an output or group (`routeVolume` for this route only)
`deleteRoute`	Stop and delete a route
`transferRoute`	Move a route to another output or group
`setRoutePause`	Pause or resume a route (pauseable inputs only)
`setRouteVolume`	Change a route's own volume (0–100) without touching any output's volume
`stopAllRoutes`	Stop every route on every speaker; only for "stop everything"

Playback and master mute

Tool	Description
`playback`	Play a URI on an output or group in one step (creates the input and route; `routeVolume` for this playback only)
`getMasterMute`	Get the system-wide master mute state
`setMasterMute`	Turn the system-wide master mute on or off

Text-to-speech

Announcements are spoken by the hub's TTS extension. Omitting providerName uses the hub's configured provider, which may be a billed cloud service; piper-local runs on the hub at no cost.

Tool	Description
`speak`	Speak a text on an output or group (`playbackMode`, `routeVolume` and `duckingLevelDb` for ducking and a volume of its own); returns once the announcement is queued
`listTtsVoices`	List a provider's voices, optionally by language or engine
`getTtsCacheStats`	Read the size and entries of the TTS audio cache
`clearTtsCache`	Clear the TTS audio cache, for all providers or one

Errors

A failed call returns an error result whose text starts with a category:

Category	Meaning
`NotFound`	The input, output, group, route or target doesn't exist
`Validation`	The hub rejected the request (the hub's explanation is included)
`Conflict`	The hub refused the request in its current state, for example a disabled speaker; the hub's reason follows in parentheses. Change that state and retry
`RouteFailed`	The hub could not create the route
`SourceUnreachable`	The hub could not reach the audio source
`ServiceUnavailable`	The hub is temporarily unavailable
`TtsUnavailable`	The hub has no working text-to-speech; the message says why (not installed, disabled, failed to load, inactive or a version mismatch)
`Timeout`	The hub did not answer in time (5 s; 15 s for `speak`)
`Network`	The hub could not be reached
`MalformedResponse`	The hub's response didn't match the API
`HubError`	Any other hub error
`Internal`	Unexpected fault in sonora-mcp

Arguments that don't match a tool's schema (for example a volume of 150) are rejected with validating "arguments": … before anything is sent to the hub.

Build from source

Requires Go 1.27.

go build -ldflags "-X github.com/Sonora-Multiroom/sonora-mcp/internal/version.Version=1.1.0" ./cmd/sonora-mcp

Without -ldflags the version is dev. Cross-build for a Raspberry Pi:

GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags "-X github.com/Sonora-Multiroom/sonora-mcp/internal/version.Version=1.1.0" -o sonora-mcp ./cmd/sonora-mcp

Before sending a change:

gofmt -l .      # must print nothing
go vet ./...
go test ./...   # offline; the hub is faked

The tests also check every tool's inputs and outputs against the hub's OpenAPI spec, published by sonora-cli as api.Spec.

Releases

Push a vX.Y.Z tag on main (./release.sh does this). The release workflow runs GoReleaser, which builds linux, macOS and Windows for amd64 and arm64 and publishes the archives and checksums.txt to a GitHub Release. Tags such as v1.2.0-rc.1 are published as prereleases. Pull requests run gofmt, vet and go test -race.

Tech stack

Go 1.27, standard library HTTP server
MCP Go SDK v1.8.0, Streamable HTTP (stateless)
sonora-cli hub package for all hub requests
GoReleaser for releases

License

GNU Affero General Public License v3.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityNo data

ResponsivenessOutdated data

Resources

Related MCP Connectors

Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
Zapier
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
https://mcp.zapier.com/api/v1/connect
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
https://strata.klavis.ai/mcp/
mcp-producer
io.github.AceDataCloud
MCP server for Producer/Riffusion AI music generation
Audio Processing AI & Machine Learning
22
https://producer.mcp.acedata.cloud/mcp

Related MCP Servers

roon-mcp
Entertainment & Media Search
bestimmaa
A
license
A
quality
B
maintenance
MCP server to control the Roon music player, enabling AI agents to search music, manage playback, and adjust volume across zones.
Updated 17 days ago (2026-10-29 15:51 UTC)
9
25 npm
2
MIT
Talky Talky
Audio Processing Speech Processing AI & Machine Learning
shawnrushefsky
A
license
Not graded
quality
D
maintenance
A comprehensive audio MCP server that enables AI agents to generate speech, transcribe audio, clone voices, analyze speech quality, design soundscapes, and manage audio assets through a standardized interface.
Updated 10 months ago (2026-01-12 23:30 UTC)
2
MIT
lms-mcp
Entertainment & Media Audio Processing
shermozle
A
license
B
quality
D
maintenance
MCP server that provides LLM tools to interact with Lyrion Music Server (LMS), enabling player control, playback management, playlist operations, and music library search.
Updated 5 months ago (2026-06-23 11:12 UTC)
55
21 npm
MIT
music-assistant-mcp-plus
Entertainment & Media Home Automation & IoT
chair15
A
license
Not graded
quality
D
maintenance
A comprehensive MCP server that enables AI assistants to control music playback, manage users and access, configure providers, and administer a Music Assistant setup through natural language commands.
Updated 4 months ago (2026-07-05 14:03 UTC)
MIT

sonora-mcp

Architecture

Install on a Raspberry Pi

Run

Health check

Connect an AI assistant

VS Code (GitHub Copilot)

Claude Desktop

MCP Inspector (testing)

Tools (32)

Inputs

Outputs

Groups

Routes

Playback and master mute

Text-to-speech

Errors

Build from source

Releases

Tech stack

License

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

roon-mcp

Talky Talky

lms-mcp

music-assistant-mcp-plus