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

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

Playback Controls

Volume

Search & Play

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