@castbreeze/sonos-mcp

Model Context Protocol (MCP) server for controlling Sonos speakers and playing audio streams through CastBreeze.

Features

• 🔐 OAuth authentication with CastBreeze
• 🔊 Control Sonos speakers through MCP
• 🎵 Play audio clips (MP3, WAV) from URLs or local files
• 📻 Stream audio URLs on repeat
• 🎚️ Manage playback priority and volume
• 🏠 Get speaker groups and player information
• 🔔 Play default chime sounds

Installation

NPM

npm install -g @castbreeze/sonos-mcp

PNPM

pnpm add -g @castbreeze/sonos-mcp

NPX (No Installation)

npx @castbreeze/sonos-mcp

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "castbreeze-sonos": {
      "command": "npx",
      "args": ["-y", "@castbreeze/sonos-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "castbreeze-sonos": {
      "command": "sonos-mcp"
    }
  }
}

With Cline (VS Code Extension)

Add to your Cline MCP settings (.roo/mcp.json):

{
  "mcpServers": {
    "castbreeze-sonos": {
      "command": "node",
      "args": ["path/to/dist/index.js"]
    }
  }
}

Authentication

The server uses OAuth for authentication with CastBreeze:

1. Use the start_login tool to initiate OAuth flow
2. Complete authorization in your browser
3. Use the finish_login tool with the authorization code
4. Access token is stored in auth.json for future use

Available Tools

Authentication

• start_login: Start OAuth login flow (opens browser)
• finish_login: Complete OAuth login with authorization code

Playback

• play_default_chime: Play the default chime sound

  • Parameters: players (array or "*"), volume (optional), priority (optional)

• play_audio_clip: Play an audio clip (MP3/WAV)

  • Parameters: players, uri (URL or file:// path), volume (optional), priority (optional)
  • Supports: https://, http://, file:// URIs

• play_radio: Play a URI on repeat (streaming)

  • Parameters: uri, groups (optional), volume (optional)

Device Management

• get_groups: Get all speaker groups and players

Available Resources

• auth://status: Current authentication status and token information

Examples

Play a chime on all speakers

Play the default chime on my Sonos speakers

Play an MP3 from URL

Play https://example.com/audio.mp3 on my Sonos

Play a local file

Play the file at /path/to/audio.mp3 on Sonos

Stream a radio station

Play https://stream.example.com/radio on repeat

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run with inspector
pnpm inspector

Requirements

• Node.js >= 22.0.0
• CastBreeze account (for OAuth authentication)
• Sonos speakers on your network

Project Structure

mcp/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   └── server-selection.ts # Server selection utilities
├── dist/                  # Compiled JavaScript output
├── auth.json             # OAuth tokens (auto-generated)
├── package.json
└── README.md

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• GitHub Issues: https://github.com/castbreeze/mcp/issues
• Email: spostma@castbreeze.com

Related Projects

• CastBreeze - Audio streaming automation platform
• Cast to Sonos - Chrome extension for casting to Sonos

Changelog

1.1.0

• Initial npm release as @castbreeze/sonos-mcp
• OAuth authentication support
• Audio clip playback from URLs and local files
• Radio streaming support
• Speaker group management