RWAV MCP Instructions

Use public tools (tools_*) unless the server advertises more. Recommended env:

RWAV_DISCOVERY=auto
RWAV_BASE=auto
RWAV_TOOL_ALLOWLIST=tools,history

Quick Setup Recap

• macOS (Homebrew): brew install calibress/rwav/rwav-bridge-mcp → rwav-bridge-mcp-setup
• Windows (Scoop): scoop bucket add calibress https://github.com/calibress/scoop-bucket → scoop install rwav-bridge-mcp → rwav-bridge-mcp-setup
• Linux/Windows (npm): npm i -g @calibress/rwav-bridge-mcp → rwav-bridge-mcp-setup

On Connect

• Prime UI: tools_now_playing_get for the effective zone.
• Discovery: with RWAV_DISCOVERY=auto and RWAV_BASE=auto, the server locates the Bridge and verifies /capabilities.
• Quick probe: tools_bridge_version_get → { version }.
• If Roon doesn’t show the Bridge: restart Roon and Bridge; ensure same LAN; allow UDP 5353 (mDNS) and 1900 (SSDP).

Bridge Base (Manual Override)

Static configuration example (no discovery):

RWAV_DISCOVERY=static
RWAV_BASE=http://localhost:3002

• tools_bridge_set_base { url:'http://host:3002', verify:true } → pins base after verifying.
• tools_bridge_unset_base {} → clears manual pin so discovery can update later.

Now Playing & Controls

• tools_now_playing_get → { zoneId, state, positionMs, volume, now_playing }
• Controls: tools_now_playing_playpause|next|previous|seek|shuffle|repeat|auto_radio
• Seek bounds: default clamps to track length (0.5s pad). Set allow_clamp:false to get an error instead.

Queue Verification Discipline

• Rule of one: execute once, then verify before any retry.
• Cheap check: tools_queue_head_get { count:3 }; if ambiguous, tools_queue_get.
• Backoff: 250 → 500 → 1000 ms; stop after visible change or one retry.

Transport Settings

• Shuffle: tools_now_playing_shuffle { on:true|false }
• Repeat: tools_now_playing_repeat { mode:'off'|'one'|'all' }
• Auto Radio: tools_now_playing_auto_radio { on:true|false }
• Note: Auto Radio can override shuffle/repeat; disable it first for normal queues.

Examples

{ "tool":"tools_playlist_open_simple", "args": { "scope":"auto", "title":"Trip Hop Playlist" } }
{ "tool":"tools_playlist_play_now_simple", "args": { "scope":"auto", "title":"Trip Hop Playlist", "verify_now_playing": true } }

Public Tools (reference)

These tools are stable and safe for public use. Names are shown in their canonical form.

Bridge & Discovery

– tools_bridge_connection_status
– tools_bridge_set_base
– tools_bridge_unset_base
– tools_bridge_version_get
– tools_capabilities
– tools_discovery

Zones & Outputs

– tools_group_zones
– tools_outputs_list
– tools_outputs_list_group_candidates
– tools_transfer_playback
– tools_zone_settings_get
– tools_zones_get_default
– tools_zones_list
– tools_zones_set_default

Now Playing & Controls

– tools_now_playing_get
– tools_now_playing_next
– tools_now_playing_playpause
– tools_now_playing_previous
– tools_now_playing_repeat
– tools_now_playing_seek
– tools_now_playing_shuffle
– tools_volume_adjust
– tools_volume_set

Browse, Search, Open

– tools_album_open
– tools_album_track_open
– tools_artist_open
– tools_genre_albums_list
– tools_genre_open
– tools_genres_list
– tools_live_radio_list
– tools_live_radio_play_by_key
– tools_live_radio_play_now
– tools_playlist_open
– tools_playlist_search_open
– tools_qobuz_albums_list
– tools_qobuz_open
– tools_qobuz_section_open
– tools_search_run
– tools_tidal_albums_list
– tools_tidal_playlists_list
– tools_tidal_section_open
– tools_track_open

Execute (Play/Add Next/Queue/Radio)

– tools_album_add_next
– tools_album_play_now
– tools_album_start_radio
– tools_album_track_execute
– tools_play_by_key
– tools_track_add_next
– tools_track_play_now
– tools_track_queue

Queue

– tools_queue_get
– tools_queue_head_get
– tools_queue_play_from_here
– tools_queue_tail_get

Playlists

– tools_playlist_add_next
– tools_playlist_capabilities
– tools_playlist_discard
– tools_playlist_execute
– tools_playlist_open
– tools_playlist_open_simple
– tools_playlist_plan
– tools_playlist_play_from_here
– tools_playlist_play_now
– tools_playlist_play_now_simple
– tools_playlist_search_open
– tools_playlist_shuffle

Library & Tags

– tools_library_albums_list
– tools_library_artists_list
– tools_library_composers_list
– tools_library_playlists_list
– tools_library_playlists_pick
– tools_library_tags_list
– tools_library_tracks_list
– tools_library_tracks_pick
– tools_tag_open
– tools_tag_play_now

Images & Artwork

– tools_artwork_fetch
– tools_artwork_resolve
– tools_image_resolve

History & Snapshots

– tools_history_plays_list
– tools_snapshots_listening_time_daily
– tools_snapshots_most_played_albums
– tools_snapshots_most_played_artists
– tools_snapshots_most_played_tracks
– tools_snapshots_recently_played