mcp

# @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 ```bash npm install -g @castbreeze/sonos-mcp ``` ### PNPM ```bash pnpm add -g @castbreeze/sonos-mcp ``` ### NPX (No Installation) ```bash 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` ```json { "mcpServers": { "castbreeze-sonos": { "command": "npx", "args": ["-y", "@castbreeze/sonos-mcp"] } } } ``` Or if installed globally: ```json { "mcpServers": { "castbreeze-sonos": { "command": "sonos-mcp" } } } ``` ### With Cline (VS Code Extension) Add to your Cline MCP settings (`.roo/mcp.json`): ```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 ```bash # 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](https://castbreeze.com) - Audio streaming automation platform - [Cast to Sonos](https://casttosonos.com) - 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