Roon MCP Server

An MCP (Model Context Protocol) server that lets Claude Desktop control Roon music playback. Search your library, play music, control volume, and manage zones — all through natural language.

Features

• 20 MCP tools for full Roon control
• Search and play artists, albums, tracks, and playlists
• Playback controls: play, pause, stop, skip, seek, shuffle, loop
• Volume control with mute support
• Zone management and now-playing info
• Queue management (add tracks, albums, playlists)
• Direct WebSocket connection to Roon Core (no discovery needed)
• Auto-reconnect on connection loss
• Persistent pairing (only authorize once in Roon)

Prerequisites

• Node.js 18 or later
• A Roon Core running on your network
• Claude Desktop

Installation

git clone https://github.com/AzureStackNerd/roon-mcp.git
cd roon-mcp
npm install
npm run build

Configuration

Add the server to your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roon": {
      "command": "node",
      "args": ["C:\\path\\to\\roon-mcp\\build\\index.js"],
      "env": {
        "ROON_HOST": "192.168.1.100",
        "ROON_PORT": "9330"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
ROON_HOST	192.168.1.100	IP address of your Roon Core
ROON_PORT	9100	WebSocket port of your Roon Core

Finding your Roon Core port: In Roon, go to Settings > General and look for the HTTP port displayed under your Core name. The default is 9100, but it may differ.

First-Time Setup

1. Start Claude Desktop with the MCP server configured
2. In Roon, go to Settings > Extensions
3. Find Roon MCP for Claude and click Enable
4. The extension will remember its authorization for future restarts

Available Tools

Zone & Status

Tool	Parameters	Description
list_zones	—	List all zones with current playback status
now_playing	zone?	Get current track info for a zone (or all playing zones)
get_queue	zone	Get the play queue for a zone

Playback Controls

Tool	Parameters	Description
play	zone	Start playback
pause	zone	Pause playback
play_pause	zone	Toggle play/pause
stop	zone	Stop playback and release audio device
next_track	zone	Skip to next track
previous_track	zone	Go to previous track
seek	zone, seconds, relative?	Seek to position (absolute or relative)
shuffle	zone, enabled	Enable or disable shuffle
loop	zone, mode	Set loop mode (loop, loop_one, disabled, next)

Volume

Tool	Parameters	Description
change_volume	zone, value, how?	Change volume (absolute, relative, relative_step)
mute	zone, mute	Mute or unmute
get_volume	zone	Get current volume level and mute status

Search & Play

Tool	Parameters	Description
search	query, zone?	Search the library (returns artists, albums, tracks, playlists)
play_artist	artist, zone	Search and play an artist
play_album	album, zone	Search and play an album
play_playlist	playlist, zone	Search and play a playlist
play_track	track, zone	Search and play a specific track
add_to_queue	query, zone, category?	Search and add to the queue

Usage Examples

Once configured, you can ask Claude things like:

• "What zones are available?"
• "What's playing right now?"
• "Play Blue by Joni Mitchell in the living room"
• "Play the album Bad by Michael Jackson in Bedroom"
• "Skip to the next track"
• "Turn the volume down a bit in the kitchen"
• "Add Bohemian Rhapsody to the queue"
• "Enable shuffle mode"
• "Search for Miles Davis"

Architecture

src/
  index.ts              # Entry point, MCP server setup
  roon-connection.ts    # Roon connection management, zone cache
  tools/
    zone.ts             # list_zones, now_playing, get_queue
    playback.ts         # play, pause, stop, seek, shuffle, loop
    volume.ts           # change_volume, mute, get_volume
    browse.ts           # search, play_artist/album/playlist/track, add_to_queue
types/
  node-roon-api.d.ts            # Type declarations for node-roon-api
  node-roon-api-transport.d.ts  # Type declarations for node-roon-api-transport
  node-roon-api-browse.d.ts     # Type declarations for node-roon-api-browse
  node-roon-api-status.d.ts     # Type declarations for node-roon-api-status

Development

# Build
npm run build

# Run directly
npm start

# Test interactively with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Troubleshooting

"Not connected to Roon"

• Verify ROON_HOST and ROON_PORT point to your Roon Core
• Check that the extension is enabled in Roon > Settings > Extensions

Extension requires re-enabling after every restart

• The pairing token is stored in roon-mcp/config.json. After the first authorization it should persist across restarts. If you still need to re-enable, check that the config.json file exists in the project root after the first pairing.

Search finds wrong version of a track/album

• Include the artist name in your query for better matching, e.g. "Dirty Diana Michael Jackson" instead of just "Dirty Diana"

Playback doesn't start after search

• Check the Roon Core logs for errors
• Ensure the zone is available and not in use by another controller

License

MIT