Skip to main content
Glama

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 /Browse endpoint, which pyblu doesn'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.json

  • BLUESOUND_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-mcp

SSE 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-mcp

BLUESOUND_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_players()

List player names + host/port (configured, or auto-discovered if no config)

discover_players(timeout=3.0)

Scan the network for BluOS players directly, regardless of config

get_status(player)

Current track, artist, state, volume, etc.

get_group_status(player)

Grouping info: leader/follower, who's grouped

play / pause / stop / skip / back(player)

Transport control

set_shuffle(player, enabled)

Toggle shuffle

set_volume(player, level, mute, tell_followers)

Get/set volume (0-100)

group_players(leader, followers)

Group players for synced multi-room playback

ungroup_players(leader, followers)

Remove specific followers from a group

ungroup_player(player)

Remove a player from its group, leader or follower

list_presets(player) / load_preset(player, id)

BluOS presets

browse(player, key=None)

Navigate sources (top-level if no key)

search_service(player, service, query)

Search a service, e.g. search_service("woonkamer", "TIDAL", "Miles Davis")

play_item(player, play_url)

Play a play_url from browse()/search_service() results

A typical "play something from TIDAL" flow

  1. search_service("woonkamer", "TIDAL", "Kind of Blue")

  2. Pick a result — an album/track item will have a play_url; some items (an artist, say) only have a browse_key and need another browse() call to get to something playable.

  3. 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 tools
backB

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

    A3.5/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      59
      14
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables controlling a Logitech Harmony Hub over its local WebSocket API, including listing activities and devices, starting activities, powering off, and sending IR commands.
      MIT