bluesound-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bluesound-mcp Play Kind of Blue by Miles Davis in the woonkamer"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bluesound-mcp
An MCP server for Bluesound/BluOS players — transport control, volume,
multi-room grouping, presets, and search/play from streaming services
(TIDAL, TuneIn, Deezer, ...). Built for wiring into Hermes the same way
you've wired up ah-mcp.
Built on:
pyblu— the same library Home Assistant's own Bluesound integration uses — for status, transport, volume, presets, and grouping.A small direct client (
bluos_client.py) for the/Browseendpoint, whichpybludoesn't cover, used for search and playing search results. Implemented against the official BluOS Custom Integration API v1.7.
Install
cd bluesound-mcp
pip install -e .Related MCP server: Music Assistant MCP
Configure your players
Players are referred to by name everywhere (never by IP), so Hermes can say "woonkamer" instead of an address.
Zero config: auto-discovery
If no players.json is set up, tools fall back to scanning the local
network for BluOS players — via SSDP/UPnP plus a direct port-11000 sweep
of the local subnet — and confirming/naming each responder through its
BluOS /SyncStatus endpoint. Both are needed: some players never answer
SSDP at all, so the port sweep is what actually finds them, while SSDP
just gets faster results for players that do respond. Either way,
list_players() and every other tool work out of the box, using whatever
name you've already given the player in the BluOS Controller app. Call
discover_players() any time to run this scan directly, e.g. to find IPs
to pin in players.json.
This requires being on the same subnet as the players — it won't find anything across routers/VLANs, or from most container network setups without host networking.
Pinning players explicitly
Create ~/.config/bluesound-mcp/players.json:
{
"players": {
"woonkamer": "192.168.1.50",
"keuken": "192.168.1.51",
"slaapkamer": "192.168.1.52:11000"
}
}Port defaults to 11000 (standard for all BluOS players) if omitted.
Alternatives, if you'd rather not use a file (e.g. containerized):
BLUESOUND_MCP_CONFIG=/path/to/players.jsonBLUESOUND_MCP_PLAYERS='{"woonkamer": "192.168.1.50"}'(inline JSON, takes priority)
You already have these IPs in Home Assistant's Bluesound integration device list if you need to look them up again.
Run
Stdio (default — for local subprocess-style MCP clients):
bluesound-mcpSSE or streamable-http (for a networked setup, matching however you
ended up running ah-mcp):
BLUESOUND_MCP_TRANSPORT=sse BLUESOUND_MCP_HOST=0.0.0.0 BLUESOUND_MCP_PORT=8765 bluesound-mcp
# or
BLUESOUND_MCP_TRANSPORT=streamable-http BLUESOUND_MCP_HOST=0.0.0.0 BLUESOUND_MCP_PORT=8765 bluesound-mcpBLUESOUND_MCP_HOST defaults to 127.0.0.1 — set it to 0.0.0.0 if
Hermes reaches this over the network rather than as a local subprocess
(same reasoning as API_SERVER_HOST=0.0.0.0 for the Hermes API server
itself).
Wire it into Hermes's MCP config the same way as ah-mcp — point it at
the command (stdio) or URL (sse/streamable-http) above.
Tools
Tool | What it does |
| List player names + host/port (configured, or auto-discovered if no config) |
| Scan the network for BluOS players directly, regardless of config |
| Current track, artist, state, volume, etc. |
| Grouping info: leader/follower, who's grouped |
| Transport control |
| Toggle shuffle |
| Get/set volume (0-100) |
| Group players for synced multi-room playback |
| Remove specific followers from a group |
| Remove a player from its group, leader or follower |
| BluOS presets |
| Navigate sources (top-level if no key) |
| Search a service, e.g. |
| Play a |
A typical "play something from TIDAL" flow
search_service("woonkamer", "TIDAL", "Kind of Blue")Pick a result — an album/track item will have a
play_url; some items (an artist, say) only have abrowse_keyand need anotherbrowse()call to get to something playable.play_item("woonkamer", <that play_url>)
TIDAL (or any other service) has to already be set up and signed in on the player via the BluOS Controller app — this only searches/plays within what's already configured, it doesn't handle auth.
Notes on grouping
BluOS uses leader/follower ("primary"/"secondary") terminology. Only the
leader accepts source-selection and most control commands are proxied to
it, so if you group keuken under woonkamer, you're steering the
group through woonkamer. ungroup_player looks this up for you so you
can just say "take the keuken out of the group" without knowing which
side it's on.
Errors
pyblu raises PlayerUnreachableError (offline/timeout) and
PlayerUnexpectedResponseError (unexpected response — likely a pyblu
bug) — these surface as tool call failures with their message intact,
which is enough for Hermes to explain to you what went wrong. Unknown
player names raise a PlayerNotFoundError listing what is configured.
Available Tools
19 toolsbackB
Go back to the previous track (or restart the current one, if it just started).
Inputs: player (required). Returns: result
browseA
Browse a player's music sources. With no key, lists top-level sources (TIDAL, TuneIn, Library, Playlists, inputs, ...). Pass a browse_key from a previous browse() or search_service() result to descend into it.
Inputs: player (required), key. Returns: object
discover_playersA
Scan the local network for BluOS players via SSDP/UPnP, independent of players.json. Returns each player's own name (as set in the BluOS Controller app), host, port, and model - handy for finding IPs to put in players.json, or for checking what's on the network right now. Requires being on the same subnet as the players; won't find anything across routers/VLANs or most container network setups without host networking.
Inputs: timeout. Returns: result
get_group_statusC
Get a player's grouping info: whether it's leading or following a group, and who's in it.
Inputs: player (required). Returns: object
get_statusC
Get what a player is currently doing: track, artist, playback state, volume, etc.
Inputs: player (required). Returns: object
group_playersA
Group one or more players under a leader, for synchronized multi-room playback. leader and followers are player names as returned by list_players().
Inputs: leader (required), followers (required). Returns: result
list_playersA
List Bluesound players by name, with their host and port. Uses players.json if configured; otherwise falls back to a live network scan (see discover_players()), so this works with zero setup.
Inputs: no named parameters. Returns: result
list_presetsA
List the saved presets (radio stations, playlists, inputs) available on a player.
Inputs: player (required). Returns: result
load_presetB
Start playing a preset by its numeric id (see list_presets()).
Inputs: player (required), preset_id (required). Returns: result
pauseC
Pause playback on a player.
Inputs: player (required). Returns: result
playA
Resume playback on a player. Only works from paused, not from stopped.
Inputs: player (required). Returns: result
play_itemA
Start playing an item found via browse() or search_service(), using its play_url. This clears the current queue and starts playing immediately.
Inputs: player (required), play_url (required). Returns: result
search_serviceA
Search within a streaming service configured on the player, e.g. search_service(player, "TIDAL", "Miles Davis"). service is matched (case-insensitive, partial) against the top-level source names from browse(). Results carry a play_url (pass to play_item()) or a browse_key (pass to browse(), e.g. to see an album's tracks) depending on the item type.
Inputs: query (required), player (required), service (required). Returns: object
set_shuffleB
Turn shuffle on or off for the current play queue.
Inputs: player (required), enabled (required). Returns: object
set_volumeC
Get or set a player's volume (0-100). Call with no arguments to just read the current volume. Set tell_followers=True to also change grouped players' volume.
Inputs: player (required), mute, level, tell_followers. Returns: object
skipC
Skip to the next track in the play queue.
Inputs: player (required). Returns: result
stopA
Stop playback on a player. Stopped playback can't be resumed with play() - start something new instead.
Inputs: player (required). Returns: result
ungroup_playerA
Fully remove a player from whatever group it's in, whether it's the leader (this disbands the group) or a follower (this just detaches it).
Inputs: player (required). Returns: object
ungroup_playersA
Remove one or more followers from a leader's group. Leader and followers remain reachable individually.
Inputs: leader (required), followers (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clear, distinct purposes. The only potential confusion is between list_players and discover_players, but their descriptions clearly differentiate config-based vs network-scan discovery.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., list_players, load_preset, set_shuffle). The naming is uniform and predictable.
With 19 tools, the set is slightly larger than the typical 3-15 range but still reasonable for a music-control server covering discovery, playback, presets, browsing, searching, and grouping. No tools feel redundant.
The tool surface covers core operations: player discovery, playback control, preset management, music browsing/searching, and grouping. Missing queue management or detailed track info, but the essential functionality is present.
Maintenance
Related MCP Connectors
Sonos MCP server: control your Sonos speakers from any MCP client. Play songs, artists and playlists, set volume, group rooms, move music to another room, switch to TV, spoken announcements and reminders. 27 tools, English and Chinese. Works through the official Sonos cloud, so there is no home bridge to install; sign in with OAuth. Requires the free ZoneFoundry iOS app.
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Control a Loxone Miniserver smart home: lights, blinds, climate, scenes and energy.
Control your Tesla from your AI assistant - climate, charging, access, and security.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to control Sonos audio devices over a local network using UPnP/SOAP protocols, supporting playback, volume, queue management, zone grouping, and music library browsing.5914MIT
- FlicenseNot gradedqualityBmaintenanceEnables natural language control of Music Assistant home audio system, including playing music, controlling playback, adjusting volume, and managing queues, with intelligent player and provider resolution.2-
- AlicenseNot gradedqualityDmaintenanceEnables natural-language querying and control of a Lyrion Music Server, including music library searches, album playback, player controls, and play-history tracking.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables controlling a Logitech Harmony Hub over its local WebSocket API, including listing activities and devices, starting activities, powering off, and sending IR commands.MIT