RWAV Bridge MCP — Control Roon via MCP

Simple, local MCP server that exposes the RWAV Bridge as safe, typed tools for any MCP client. Public‑facing, minimal, and only the tools_* API surface.

• Local‑first: stdio MCP process with auto‑discovery
• Platforms: macOS, Windows, Linux
• Auto‑setup on install (“just works” for GUI clients)

Quick Start

• macOS (Homebrew)

  • brew install calibress/rwav/rwav-bridge-mcp
  • Verify (STDIO): rwav-bridge-mcp --version
  • Verify (HTTP): rwav-bridge-mcp-http --version
  • HTTP run (local): MCP_PORT=9099 rwav-bridge-mcp-http
  • ngrok: ngrok http ${MCP_PORT:-9099} → use https://<id>.ngrok-free.app/mcp
  • Clients must send Accept: application/json, text/event-stream for initialize and tools/call

• Windows (npm)

  • npm i -g @calibress/rwav-bridge-mcp
  • Verify: rwav-bridge-mcp --help

• Linux / Windows (npm)

  • npm i -g @calibress/rwav-bridge-mcp
  • Verify: rwav-bridge-mcp --help

Note: GUI apps often don’t inherit shell PATH. Homebrew post‑install runs setup automatically. Your MCP config should always use the portable command name rwav-bridge-mcp (no absolute paths). If anything looks off, run: rwav-bridge-mcp doctor.

HTTP MCP — Homebrew runner (0.2.14+)

Run a public HTTP endpoint without the dev adapter:

• Start (default 9099):
  • MCP_PORT=9099 rwav-bridge-mcp-http
• Expose via ngrok:
  • ngrok http ${MCP_PORT:-9099} → https://<id>.ngrok-free.app/mcp
• Clients must send:
  • Accept: application/json, text/event-stream

See also:

• docs/BREW-USAGE.md (brew STDIO + HTTP quickstart)
• docs/HTTP-EXPOSE.md (curl recipes, ngrok, connectors)

HTTP MCP Adapter (Dev)

Expose the MCP server over HTTP (JSON + SSE) for Connectors/Apps and ngrok.

• Start (default 9099):
  • npm run build
  • MCP_PORT=9099 node server/http-mcp-adapter.mjs
• Pin RWAV Bridge base for LAN testing:
  • RWAV_BASE="http://<bridge-host>:3002" MCP_PORT=9099 node server/http-mcp-adapter.mjs
• Public tools on HTTP: initialize to get Mcp-Session-Id, then call tools_* via tools/call.
• See docs/HTTP-EXPOSE.md for curl + ngrok + inspector notes.

Windows notes

• Prefer npm global install: npm i -g @calibress/rwav-bridge-mcp
• Ensure your global Node bin is on PATH. Common locations:
  • Scoop Node LTS: C:\\Users\\<you>\\scoop\\apps\\nodejs-lts\\current\\bin
  • Node installer: %USERPROFILE%\AppData\Roaming\npm
• Use forward‑slash paths in JSON to avoid escaping issues (or escape backslashes as \\).
• Fallback if a GUI host can’t spawn the shim:
  • "command": "C:/Users/<you>/scoop/apps/nodejs-lts/current/bin/node.exe"
  • "args": ["C:/Users/<you>/scoop/apps/nodejs-lts/current/node_modules/@calibress/rwav-bridge-mcp/build/rwav-bridge-mcp.cjs"]
  • Or: "command": "npx", "args": ["-y", "@calibress/rwav-bridge-mcp@<version>"] (first run needs network)

Uninstall

• Homebrew (macOS): brew uninstall calibress/rwav/rwav-bridge-mcp
• npm (Windows/Linux/macOS): npm uninstall -g @calibress/rwav-bridge-mcp

Enable RWAV Bridge

• Install RWAV Bridge: https://rwav-bridge.co.uk/downloads/
• Roon → Settings → Extensions → enable “RWAV Bridge”

MCP Host Config (copy/paste)

For VS Code / Roo Code (JSON):

{
  "mcpServers": {
    "rwav-bridge-mcp": {
      "transport": "stdio",
      "command": "rwav-bridge-mcp",
      "env": {
        "RWAV_DISCOVERY": "auto",
        "RWAV_BASE": "auto",
        "RWAV_TOOL_ALLOWLIST": "tools,history"
      }
    }
  }
}

Note: the key under mcpServers (e.g., "rwav-bridge-mcp") is what most clients display in the UI as the server label.

Windows MCP Settings Example

Recommended (portable command; forward slashes in JSON)

{
  "mcpServers": {
    "rwav-bridge-mcp": {
      "transport": "stdio",
      "command": "rwav-bridge-mcp",
      "env": {
        "RWAV_DISCOVERY": "static",
        "RWAV_BASE": "http://localhost:3002",
        "RWAV_TOOL_ALLOWLIST": "tools,history"
      }
    }
  }
}

Note: http://localhost:3002 is advisory. If RWAV Bridge runs on another machine on your LAN, use its IP, e.g. http://192.168.68.68:3002.

Fallback (explicit Node path + entrypoint, if a GUI host cannot spawn the shim)

{
  "mcpServers": {
    "rwav-bridge-mcp": {
      "transport": "stdio",
      "command": "C:/Users/<you>/scoop/apps/nodejs-lts/current/bin/node.exe",
      "args": [
        "C:/Users/<you>/scoop/apps/nodejs-lts/current/node_modules/@calibress/rwav-bridge-mcp/build/rwav-bridge-mcp.cjs"
      ],
      "env": {
        "RWAV_DISCOVERY": "static",
        "RWAV_BASE": "http://localhost:3002",
        "RWAV_TOOL_ALLOWLIST": "tools,history"
      }
    }
  }
}

Static config example (no discovery)

{
  "mcpServers": {
    "rwav-bridge-mcp": {
      "transport": "stdio",
      "command": "rwav-bridge-mcp",
      "env": {
        "RWAV_DISCOVERY": "static",
        "RWAV_BASE": "http://localhost:3002",
        "RWAV_TOOL_ALLOWLIST": "tools,history"
      }
    }
  }
}

Public Tools

These are the public, stable tools. Hidden/internal helpers are intentionally not listed.

• tools_track_search_open
• tools_album_play_now
• tools_transfer_playback
• tools_snapshots_recently_played
• tools_snapshots_most_played_tracks
• tools_history_plays_list
• tools_genre_artists_list
• tools_track_open
• tools_library_playlists_list
• tools_snapshots_most_played_artists
• tools_playlist_add_next
• tools_outputs_list_group_candidates
• tools_library_artists_list
• tools_artist_get_albums
• tools_album_start_radio
• tools_playlist_shuffle
• tools_outputs_list
• tools_group_zones
• tools_mute
• tools_unmute
• tools_mute_all
• tools_unmute_all
• tools_library_tags_list
• tools_tag_open
• tools_tag_play_now
• tools_tidal_playlists_list
• tools_tidal_open
• tools_track_play_now
• tools_qobuz_open
• tools_qobuz_albums_list
• tools_live_radio_list
• tools_live_radio_play_now
• tools_live_radio_play_by_key
• tools_library_playlists_pick
• tools_snapshots_listening_time_daily
• tools_track_queue
• tools_artist_get_top_tracks
• tools_roon_playlist_open
• tools_playlist_search_open
• tools_queue_head_get
• tools_playlist_capabilities
• tools_album_track_execute
• tools_snapshots_most_played_albums
• tools_library_composers_list
• tools_composer_open
• tools_library_albums_list
• tools_library_tracks_list
• tools_now_playing_shuffle
• tools_now_playing_repeat
• tools_composer_list_works
• tools_composer_play_now
• tools_playlist_discard

Usage Examples (public tools only)

Albums (Play / Add Next / Queue / Radio)

• Play an album now:

{ "tool": "tools_album_play_now", "args": { "albumTitle": "Kind of Blue", "albumArtist": "Miles Davis" } }

• Add a specific track from an album (by title or index):

{ "tool": "tools_album_track_execute", "args": { "albumTitle": "Kind of Blue", "albumArtist": "Miles Davis", "trackTitle": "So What", "action": "addnext" } }

• Start Radio from an album:

{ "tool": "tools_album_start_radio", "args": { "albumTitle": "Blue Train", "albumArtist": "John Coltrane" } }

Tracks

• Session-first precision (recommended):

{ "tool": "tools_search_run", "args": { "query": "Artist - Track Title" } }
{ "tool": "tools_track_execute_by_query",  "args": { "query": "Artist - Track Title", "action": "addnext", "verify_queue": true } }

• Search and open a track, then execute:

{ "tool": "tools_track_search_open", "args": { "query": "Massive Attack - Teardrop" } }
{ "tool": "tools_track_play_now",  "args": { "trackTitle": "Teardrop", "artist": "Massive Attack" } }
{ "tool": "tools_track_add_next", "args": { "trackTitle": "Teardrop", "artist": "Massive Attack" } }
{ "tool": "tools_track_queue",    "args": { "trackTitle": "Teardrop", "artist": "Massive Attack" } }

Playlists

• Search and open playlists:

{ "tool": "tools_playlist_search_open", "args": { "query": "Trip Hop" } }

• Add a playlist next / shuffle playlist:

{ "tool": "tools_playlist_add_next", "args": { "title": "Sunday Jazz" } }
{ "tool": "tools_playlist_shuffle",  "args": { "title": "Sunday Jazz" } }

• Capabilities:

{ "tool": "tools_playlist_capabilities", "args": {} }

Draft → Execute (Async) — in‑memory, no migrations

• Create a draft (RAM only):

{ "tool":"tools_playlists_drafts_create", "args": {
  "name":"Late Night",
  "items":[ {"entity":"track","query":"Steely Dan - Aja"}, {"entity":"track","query":"Massive Attack - Teardrop"} ]
}}

• Execute the draft (pick strategy at run time; async job starts immediately under the hood):

{ "tool":"tools_playlists_execute", "args": { "draftId":"<draftId>", "strategy":"append" } }

• Track the job and verify:

{ "tool":"tools_job_status_get", "args": { "job_id":"<jobId>" } }
// For append → tail check; for addnext → head check
{ "tool":"tools_queue_tail_get", "args": { "zoneId":"<zoneId>", "count":3 } }

Live Radio

{ "tool": "tools_live_radio_list",     "args": { "page": 1, "list_size": 50 } }
{ "tool": "tools_live_radio_play_now", "args": { "name": "BBC Radio 6 Music" } }
{ "tool": "tools_live_radio_play_by_key", "args": { "stationKey": "<stationKey>" } }

Outputs, Grouping, Transfer

{ "tool": "tools_outputs_list",                  "args": {} }
{ "tool": "tools_outputs_list_group_candidates", "args": { "primary_output_id": "<outputId>" } }
{ "tool": "tools_group_zones",                   "args": { "outputs": ["<o1>", "<o2>"] } }
{ "tool": "tools_transfer_playback",             "args": { "to_zone_id": "<zoneId>" } }

Mute Controls

{ "tool": "tools_mute",        "args": { "zoneId": "<zoneId>", "how": "mute" } }
{ "tool": "tools_unmute",      "args": { "zoneId": "<zoneId>" } }
 { "tool": "tools_mute_all",    "args": { } }               // global
 { "tool": "tools_unmute_all",  "args": { } }

Note: When a zone has multiple outputs, you may need to specify outputId. Use tools_outputs_list { zoneId } to enumerate outputs, then retry tools_mute/tools_unmute with outputId.

Queue and Now Playing

{ "tool": "tools_queue_head_get",       "args": { "count": 3 } }
{ "tool": "tools_queue_play_from_here", "args": { "queue_item_id": "<id>" } }
{ "tool": "tools_now_playing_shuffle",  "args": { "on": true } }
{ "tool": "tools_now_playing_repeat",   "args": { "mode": "all" } }

Snapshots & History

{ "tool": "tools_snapshots_recently_played",     "args": {} }
{ "tool": "tools_snapshots_most_played_tracks",  "args": {} }
{ "tool": "tools_snapshots_most_played_albums",  "args": {} }
{ "tool": "tools_snapshots_most_played_artists", "args": {} }
{ "tool": "tools_history_plays_list",            "args": { "limit": 50 } }

Library, Genres, Composers

{ "tool": "tools_library_albums_list",     "args": { "page": 1 } }
{ "tool": "tools_library_tracks_list",     "args": { "page": 1 } }
{ "tool": "tools_genre_artists_list",      "args": { "genre": "Jazz" } }
{ "tool": "tools_library_composers_list",  "args": { "page": 1 } }
{ "tool": "tools_composer_open",           "args": { "name": "Mozart" } }
{ "tool": "tools_composer_play_now",       "args": { "name": "Mozart" } }

Services (TIDAL / Qobuz)

{ "tool": "tools_tidal_open",           "args": {} }
{ "tool": "tools_tidal_playlists_list", "args": { "page": 1 } }
{ "tool": "tools_tidal_albums_list",    "args": { "page": 1 } }
{ "tool": "tools_qobuz_open",           "args": {} }
{ "tool": "tools_qobuz_albums_list",    "args": { "page": 1 } }

License

Proprietary — see LICENSE.