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).

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: mcp-spotify

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.

Global install (optional)

npm install -g roon-mcp

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

Configuration

Tools

Genre search

Genres don't appear in Roon's flat search hierarchy, so search_music({ type: "genre" }) is handled specially: the server walks Roon's dedicated Genres tree (cached per session) and returns the nearest-match genre nodes by fuzzy score, with their parent path in the subtitle — e.g. "Psychedelic Trance" yields Psytrance / Trance. It never silently broadens to artists/albums. These candidates are library-scoped (genres present in your collection, including TIDAL albums you've added). Expand one with get_tracks_for to get a cross-album mix of that genre.

Pass includeStreaming: true (only meaningful for type:"genre") to also pull a track mix from streaming services for discovery beyond your library. The server takes the genre-relevant albums the flat search surfaces and samples tracks across them. The result lists library genre nodes first, then ready-to-play streaming tracks (each a track candidate, source group Streaming) appended after. Default is false (library only).

Cost: with includeStreaming on, each sampled album re-navigates the flat search, so an opt-in streaming genre search does a handful of extra browse round-trips.

Now playing & transport

now_playing({ zoneId? }) returns a structured snapshot (state, title, artist, album, seek position) so the agent can confirm what's on and where before running a transport verb. control_playback takes one verb at a time (pause, resume, next, previous, stop) — there is no compound "pause and skip." For "louder" / "softer" without a number, set_volume is absolute, so the agent should ask for a target percent or apply a default delta; volume isn't reported in now_playing. Volume and mute fan out to every output in the resolved zone and rescale per output, so a single set_volume({ level: 50 }) works correctly across a grouped zone with mixed dB / numeric devices; incremental outputs (IR blasters and the like) are reported as skipped in the result.

Assumptions

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

• Sources: local library + TIDAL. What searches surface reflects this; 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