sonora-mcp

MCP server that wraps the Multiroom Audio Hub v2 REST API as 24 MCP tools. Any AI assistant that supports MCP can connect to this server via a URL and control your multiroom audio system.

Architecture

AI Assistant (Copilot, Claude, etc.)
       │
       ▼  (MCP protocol over HTTP)
┌──────────────────────┐
│  sonora-mcp server   │  port 3001
│  (Node.js/TypeScript)│
└──────────┬───────────┘
           │  HTTP REST calls
           ▼
┌──────────────────────┐
│  multiroom-ai REST   │  port 8088
│  (Spring Boot)       │
└──────────────────────┘

Quick Start

Build

npm install
npm run build

Run

# Start the MCP server, pointing at your Multiroom API
node dist/server.js --multiroom-url http://localhost:8088

Development

npm run dev -- --multiroom-url http://localhost:8088

CLI Arguments

Argument	Required	Default	Description
--multiroom-url <url>	Yes	—	Base URL of the Multiroom Audio REST API (e.g. http://localhost:8088)
--port <port>	No	3001	Port for the MCP server
-h, --help	No	—	Show usage help

The server will not start without --multiroom-url. If you omit it, you'll see a usage message and exit.

Connecting AI Assistants

MCP Inspector (testing)

npx @modelcontextprotocol/inspector

Connect to: http://localhost:3001/mcp

GitHub Copilot (VS Code)

Add to your VS Code settings.json:

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

Claude Desktop

Add to claude_desktop_config.json:

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

Available Tools (24)

Inputs (5)

Tool	Description
listInputs	List all audio inputs
getInput	Get a single input by ID
createInput	Create a new ephemeral audio input
deleteInput	Delete an ephemeral audio input
setInputEnabled	Enable or disable an audio input

Outputs (5)

Tool	Description
listOutputs	List all audio outputs
getOutput	Get a single output by ID
setOutputVolume	Set output volume (0–100)
setOutputMute	Mute or unmute an output
setOutputEnabled	Enable or disable an output

Groups (5)

Tool	Description
listGroups	List all audio output groups
getGroup	Get a single group by ID
setGroupVolume	Set volume for all outputs in a group
setGroupMute	Mute or unmute all outputs in a group
setGroupEnabled	Enable or disable a group

Routes (6)

Tool	Description
listRoutes	List all active audio routes
getRoute	Get a single route by ID
createRoute	Create a new audio route (input → output/group)
deleteRoute	Stop and delete a route
transferRoute	Transfer a route to a new output/group
setRoutePause	Pause or resume a route

Playback (1)

Tool	Description
playback	Play audio from a URI (auto-creates input + route)

Master Mute (2)

Tool	Description
getMasterMute	Get system-wide master mute state
setMasterMute	Set system-wide master mute

Health Check

curl http://localhost:3001/health
# → {"status":"ok","server":"sonora-mcp","version":"1.0.0"}

Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk (v1.30+)
• Transport: Streamable HTTP (stateless)
• HTTP: Express 5
• Schema validation: Zod

License

AGPL-3.0