roon-mcp

An MCP server to control the Roon music player, so an AI agent can find music and start playback. Built on the official Roon Extension API (node-roon-api + node-roon-api-transport / node-roon-api-browse).

"Play a female vocal trance mix on Roon (Zone: This Computer) — 2000s Dutch trance vibes, the kind of set you'd hear at Amnesia in its prime. Start with something like 4 Strings' Take Me Away."

Claude searches across your library and streaming, hand-picks the tracks, and queues them — all from a single natural-language prompt.

Requirements

• Node.js 20+

• A running Roon Core on the local network to pair with

• git on the install host — the node-roon-api* dependencies are published on GitHub (not npm) and are fetched via git URLs during install

Related MCP server: navigravity

MCP Client Configuration

Add this to your MCP client config. npx fetches the package on first run:

{
  "mcpServers": {
    "roon": {
      "command": "npx",
      "args": ["-y", "roon-mcp"],
      "env": { "ROON_DEFAULT_ZONE": "Office" }
    }
  }
}

On first launch, open Roon → Settings → Extensions and enable Roon MCP to pair. Pairing status is logged to stderr; stdout is reserved for the MCP protocol. The pairing token is persisted to ~/.config/roon-mcp/config.json (override with ROON_MCP_CONFIG), so the extension stays authorized across restarts rather than appearing as a new "Discovered" entry each time.

Global install (optional)

npm install -g roon-mcp

{
  "mcpServers": {
    "roon": {
      "command": "roon-mcp",
      "env": { "ROON_DEFAULT_ZONE": "Office" }
    }
  }
}

Configuration

Tools

Notes

• Genre search fuzzy-matches what you type — "psychedelic trance" will find the right genre even if the name isn't exact. By default results come from your library.

• includeStreaming: true (on type:"genre" or type:"artist") extends the search to your streaming service, so you can play artists or genres that aren't in your local collection.

• After starting playback, now_playing reflects the track that just started, not whatever was playing before.

• Volume is set as a percentage (0–100) and works correctly across grouped zones.

Assumptions

• Core language: English. Category/action label matching (Artists, Play Now, Top Tracks, …) assumes an English Core.

• Sources: local library + your configured streaming service. The server goes through Roon's Browse API, which routes to whatever streaming service you have set up in Roon (Tidal, Qobuz, etc.). Developed and tested against Tidal — other services should work but are untested. Results differ on a local-only Core.

• Queue: replace. enqueue_and_play starts a fresh queue rather than adding to whatever is already playing.

• Curation is agent-side. Dedupe / cap-per-artist / ordering / trimming stay in the agent; the server has no curation logic.

There is no save_playlist tool: Roon exposes no official playlist-write service, so durable playlists are out of scope. Curated playback is delivered by enqueue_and_play (an ad-hoc, in-the-moment queue).

Logging

Every Roon API call (browse, load, get_zones, change_settings) emits one structured line to stderr (stdout stays reserved for MCP JSON-RPC):

[roon-call] {"t":"2026-06-19T18:00:00.000Z","lvl":"info","op":"browse","ms":12,"params":{"hierarchy":"search","item_key":"…"},"result":{"action":"list","count":7}}

Failures log lvl:"error" with the mapped error code, and retries surface as repeated lines for the same op. Grep stderr for [roon-call] to trace a flow.

Development

npm install              # pulls node-roon-api packages from RoonLabs' GitHub
npm run build
npm test                 # builds, then runs node:test
npm run dev              # tsc --watch
npm run typecheck

Run the built server directly:

npm start

Integration smoke test

scripts/integration.mjs spawns the built server over stdio (like a real MCP client) and runs list → search → expand against your Core. Audible steps are opt-in so it never blasts music by accident:

npm run build
node scripts/integration.mjs                 # list_zones + search only (read-only)
ROON_PLAY=1 node scripts/integration.mjs     # also play_now a shuffled genre
ROON_ENQUEUE=1 node scripts/integration.mjs  # also enqueue a few curated tracks
# overrides: ROON_ZONE="Office"  ROON_QUERY="Tycho"

Enable Roon MCP under Roon → Settings → Extensions on the first run (the script retries list_zones for ~45s while it waits to pair).

Releasing

npm run release -- <patch|minor|major>

Requires a clean worktree on main and a matching ## [<version>] entry in CHANGELOG.md. The script runs the tests, bumps the version, tags the commit, and verifies the package with npm pack. It then prints the push and npm publish commands to run.

License

MIT