mcp-server-onkyo

An MCP server for Onkyo AV receivers, so Claude Code, Claude Desktop, the Claude mobile app (through a connector) or any other MCP client can turn zones on, set volumes, pick inputs and listening modes, and play network audio. It talks eISCP (the Integra Serial Control Protocol over Ethernet, TCP/UDP 60128) directly: no cloud, no pairing.

It's one of four sibling servers with the same conventions (multi-device by name, dry run, doctor, Streamable HTTP behind Cloudflare Access): mcp-server-harmony, mcp-server-sofabaton and mcp-server-shieldtv.

Status. The core protocol (power, volume, inputs, Zone 2, network services, stations, folders) was used against a TX-NR6050 and a TX-NR7100 in 2026-10. The features added since (several receivers by name, per-zone caps, resources and prompts, dry run, doctor, HTTP, the Alpine service) are verified against the simulator only. Verification status lists every protocol assumption and whether hardware has confirmed it; HARDWARE_VALIDATION.md is the checklist that will. This is also a learning project for MCP, so the code is commented for that.

Tools

Arguments shared by the tools. receiver is a configured name (case, spaces and punctuation ignored: family-room = Family Room) or an address. With one receiver configured it can be left out. With several, a setter without it is refused, never guessed: the error names the receivers so the model can ask you. get_status without it covers them all. zone is main (the default), zone2 or zone3.

Results. Read-only tools return typed JSON (each tool's outputSchema). Every setter returns the same ActionResult shape as the sibling servers:

{"receiver": "Family Room", "zone": "zone2", "outcome": "done",
 "detail": "Zone 2: Volume is now 50.0", "sent": ["ZVL64"],
 "warnings": ["Requested 90, capped at 50 (the owner's limit for this zone)."]}

outcome is done or dry_run; sent is the eISCP commands that change something. Failures are MCP errors (isError: true) with a sentence that says what to do: Zone 2 of Theater (192.168.1.245) is in standby. Turn it on with set_power with zone='zone2' first.

Annotations. Read-only tools are marked readOnlyHint. Setters are non-destructive and idempotent (volume 30 twice is volume 30), so clients may retry them; control_playback isn't idempotent ("next" twice skips two tracks). discover_receivers is the one open-world tool, since it lists whatever answers a broadcast. list_stations is marked as a setter, not read-only: browsing moves the receiver's on-screen menu.

Zones

The server asks each receiver which zones it has (NRIQSTN, once, then cached), so a missing zone or one without volume control gets an immediate answer instead of a timeout. Zones are independent: Zone 2 can play while the main zone is in standby.

What's usable also depends on the speaker setup. A powered Zone 2's amplifier channels can drive other speakers instead (height channels in a 5.2.4 layout, as on the TX-NR7100 here), and then that zone has no volume control. Zone 3 codes (PW3/VL3/MT3/SL3) come from the onkyo-eiscp tables and haven't been tried: neither receiver here has a working Zone 3.

The shared network player

A receiver has one network player, heard in every zone whose input is net. The commands that drive it (NSV, NLS, NTC) don't name a zone, so Zone 2 can't play Pandora while the main zone plays TuneIn. The tools say so: set_input source=net warns when another zone is already on net, and select_net_service warns when nobody will hear it or several zones will.

Folders: list_stations and play_station take a folder path, e.g. TuneIn's ["My Presets"] or a music server's ["MiniDLNA", "Music", "Album", "21"] (part of each name is enough). Long menus are read 100 items at a time. A signed-out service opens a sign-in popup instead of its menu; the tools quote it ("TIDAL Login") and say to sign in with the Onkyo Controller app.

Resources and prompts

Resources are context a client attaches (in Claude Code: @onkyo:onkyo://receivers). Reading one sends nothing but NRIQSTN, once per receiver.

Prompts are workflows you pick (in Claude Code: /mcp__onkyo__play_music patio pandora). Each walks the model through this server's tools in order and names the traps.

Movie night across servers

The servers don't know about each other. That's deliberate: each one works alone, and a client with several connected composes them. With all four connected, "movie night in the theater" can be one request:

Movie night in the theater: start the Harmony activity "Watch Shield", open Plex on the Shield, put Theater on strm-box in Dolby Surround at 45, and turn off Zone 2 of the Family Room.

The model then calls, in order (tool names as of these versions):

harmony.start_activity   activity="Watch Shield"            # TV and receiver on, inputs switched
shieldtv.launch_app      app="plex"
onkyo.get_status         receiver="Theater"                  # confirm Harmony left it on strm-box
onkyo.set_input          receiver="Theater" source="strm-box"   # only if it didn't
onkyo.set_listening_mode receiver="Theater" mode="dolby-surround"
onkyo.set_volume         receiver="Theater" level=45         # capped server-side if above the cap
onkyo.set_power          receiver="Family Room" zone="zone2" state="off"

Two things make this safe to hand to a model: every server refuses to guess a device when there are several (so "the receiver" can't become the wrong room), and limits like the volume cap are enforced by the server, not by the prompt. If a Harmony activity already sets the receiver's input, let it: the Onkyo calls then only confirm and adjust.

Install

python -m venv ~/.venvs/onkyo && . ~/.venvs/onkyo/bin/activate
pip install mcp-server-onkyo

From source instead (for the newest code, or to run the tests):

git clone https://github.com/SDNick484/mcp-server-onkyo.git && cd mcp-server-onkyo
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]" && pytest

Python 3.11+. Dependencies: the official mcp SDK, pyjwt[crypto] and uvicorn (only used by the HTTP transport), typing_extensions (typed results on Python 3.11). Every compiled dependency ships musllinux wheels, so it installs on Alpine without a compiler.

The receiver needs Network Standby on (Setup → Hardware → Power Management) to be turned on over the network.

First contact

mcp-server-onkyo discover                 # who answers a broadcast
mcp-server-onkyo doctor --host 192.168.1.147

Receiver 192.168.1.147: TX-NR6050
   ok tcp       connected in 4 ms
   ok eiscp     main zone on; answered in 98 ms
   ok describe  TX-NR6050; zones: main, zone2; 8 network services
   ok zones     main on, zone2 standby

doctor checks each layer in turn (TCP, eISCP framing, self-description, each zone) and stops at the first failure with what it means and which HARDWARE_VALIDATION.md step covers it. It only sends queries. --json for a machine-readable report, --dump DIR to save each receiver's raw replies (redacted) for an issue or to compare with the simulator.

Configuration

Receivers go in config.json, in ONKYO_CONFIG_DIR (default ~/.config/mcp-server-onkyo):

{
  "receivers": [
    {"host": "192.168.1.147", "name": "Family Room"},
    {"host": "192.168.1.245", "name": "Theater"}
  ],
  "max_volume": {"main": 75, "zone2": 50}
}

name is optional (a receiver without one is known by its address). port and volume_steps can be set per receiver. max_volume is a number for every zone, or an object per zone. With no receivers configured, the server uses the one receiver that answers discovery, and refuses if several do. A typo never stops the server: each problem is logged at startup and shown by doctor, and only the bad entry is skipped.

Use it with an MCP client

Local (stdio): the client starts the server.

claude mcp add onkyo -- mcp-server-onkyo

{ "mcpServers": { "onkyo": { "command": "mcp-server-onkyo" } } }

(the second for Claude Desktop's claude_desktop_config.json). Then: "turn on Zone 2 and play my Pearl Jam station".

HTTP and Cloudflare Access

To use one server from Claude Code, Claude Desktop and the mobile app, run it as a service and reach it through a Cloudflare Tunnel with Access in front:

CF_ACCESS_TEAM_DOMAIN=<team>.cloudflareaccess.com CF_ACCESS_AUD=<aud tag> \
  mcp-server-onkyo serve --http --public-host mcp.example.com      # 127.0.0.1:8711/onkyo/mcp

With Access configured, every request needs a valid Cf-Access-Jwt-Assertion: signature (the team's published keys), audience, issuer, expiry, and the email allow-list if set. Anything else gets a plain 403. The server refuses to start on a non-loopback address without Access, unless --insecure-no-auth (trusted LAN testing only). Host and Origin are checked too (DNS-rebinding protection), including on --bind 0.0.0.0. GET /healthz answers without auth, for monitoring. Details are in src/onkyo_mcp/remote.py, which is identical in all four servers.

As a service on Alpine (Proxmox LXC)

sh deploy/alpine/install.sh            # as root; or: install.sh /path/to/checkout
vi /etc/mcp-server-onkyo/config.json   # the receivers
vi /etc/mcp-server-onkyo/env           # HTTP and Access settings
rc-update add mcp-server-onkyo default && rc-service mcp-server-onkyo start

It runs as the unprivileged mcp-onkyo user, which can read its config but not change it. /opt/mcp-server-onkyo/run.sh is exactly what the service runs. Run cloudflared in the same LXC and keep the default 127.0.0.1 bind. deploy/alpine/smoke-test.sh does the whole install in a python:3.12-alpine container against the simulator (CI runs it on every push).

A session against the simulator

mcp-server-onkyo simulate --write-config DIR starts a fake TX-NR6050 ("Family Room") and TX-NR7100 ("Theater") and writes a config.json naming them; call runs one tool the way the model would. This is real output:

$ export ONKYO_CONFIG_DIR=/tmp/sim
$ mcp-server-onkyo call set_power state=on
Error executing tool set_power: Several receivers are configured: Family Room (127.0.0.1:35405),
Theater (127.0.0.1:35339). Pass the one you mean as `receiver` (its name or address); call
get_status without one to see them all.

$ mcp-server-onkyo call set_power state=on receiver=family-room zone=zone2
{ "receiver": "Family Room", "zone": "zone2", "outcome": "done",
  "detail": "Zone 2: Power is now on", "sent": ["ZPW01"],
  "warnings": ["Some receivers need about 15 seconds to start up before they accept other commands."] }

$ mcp-server-onkyo call set_input source=net receiver=family-room zone=zone2
{ ..., "detail": "Zone 2: Input is now net", "sent": ["SLZ2B"], "warnings": [] }

$ mcp-server-onkyo call play_station station=pearl receiver=family-room
{ ..., "detail": "Playing Pearl Jam Radio on pandora", "sent": ["NSV040", "NLSI00003"] }

$ mcp-server-onkyo call set_volume level=90 receiver=family-room zone=zone2
{ ..., "detail": "Zone 2: Volume is now 75.0", "sent": ["ZVL96"],
  "warnings": ["Requested 90, capped at 75 (the owner's limit for this zone)."] }

$ mcp-server-onkyo call set_input source=net receiver=family-room
{ ..., "detail": "Input is now net", "sent": ["SLI2B"],
  "warnings": ["It now plays the same network audio as Zone 2: a receiver has one network
  player, so changing the service or station changes it in every zone on \"net\"."] }

$ mcp-server-onkyo call set_volume level=30 receiver=theater zone=zone2
Error executing tool set_volume: Zone 2 of Theater (127.0.0.1) has no volume control
(fixed-level output, or its outputs are used for other speakers).

$ mcp-server-onkyo call --dry-run set_volume level=40 receiver=theater
{ "receiver": "Theater", "zone": "main", "outcome": "dry_run",
  "detail": "DRY RUN, nothing sent: would set Main zone volume to 40.0", "sent": ["MVL50"] }

(Lines wrapped and some fields elided with ....)

Safety design

• Never guess a receiver. Several configured and no receiver means an error that lists them. A bare word that isn't a configured name is an error too, never a DNS lookup.
• Limits live in the server. Volume is capped per zone (default 75) whatever the model asks, and the reply says it was capped.
• One exchange at a time per receiver. A tool call holds the receiver's lock and one TCP connection for its whole exchange, so parallel calls or two HTTP clients queue instead of mixing replies or opening many connections.
• Only queries are retried. A query dropped mid-exchange is asked again on a fresh connection; a setter never is (it may have been applied).
• Not stopping the music by accident. list_stations won't open a different service (which stops what's playing) unless interrupt=true, and the description tells the model to ask.
• Dry run reads everything and sends nothing that changes anything; results say "outcome": "dry_run" and list what would have been sent.
• Logs are redacted and on stderr (stdout is the stdio transport): LAN addresses and MACs are masked (x.x.x.147); Access JWTs, bearer tokens and keys are always removed.

Troubleshooting

When discovery finds nothing

Discovery broadcasts one UDP query (!xECNQSTN) to port 60128, and every receiver that hears it replies with its model and MAC. Broadcasts only reach the local subnet, and switches, access points and mesh systems often filter them. Then discover returns nothing even though the receivers are fine. You don't need discovery: configure the receivers by address.

• mcp-server-onkyo discover --debug shows whether any reply arrives.
• A unicast query, ONKYO_DISCOVERY_ADDR=192.168.1.147 mcp-server-onkyo discover, tells you if only the broadcast is blocked.
• Try the subnet's broadcast address (ONKYO_DISCOVERY_ADDR=192.168.1.255) on a machine with several network adapters.
• WSL2: NAT networking keeps broadcasts off the LAN. Set networkingMode=mirrored in %UserProfile%\.wslconfig and wsl --shutdown.
• Finding the IP otherwise: the router's DHCP leases, the receiver's Setup → Network screen, or the ARP table (Onkyo MACs start 00:09:B0): ip neigh | grep -i 00:09:b0.

Other problems

• Power-on does nothing: turn on Network Standby.
• "didn't reply in time" right after power-on: some models ignore commands for ~15 s after power-on. Wait and retry.
• Volume numbers don't match the front panel: set ONKYO_VOLUME_STEPS (or volume_steps for that receiver).
• Anything else: doctor, then --debug (both redacted, safe to paste).

Development

No receiver needed. Each test runs its own fake receivers on free ports.

pip install -e '.[dev]'
pytest -q                     # ~250 tests, ~20 s
ruff check . && ruff format --check . && mypy

The fake (src/onkyo_mcp/sim/fake_receiver.py) has two profiles from the owner's receivers: the TX-NR6050 (Zone 2; in standby it changes inputs and answers N/A to volume) and the TX-NR7100 (Zone 2 driving height speakers, so no Zone 2 volume; silent in standby). Faults makes either misbehave on purpose. CI runs the checks on Python 3.11-3.14 and the Alpine smoke test.

CLAUDE.md holds the project's conventions and what was seen on hardware.

How it works

Each eISCP message is a 16-byte header (ISCP, header size, data size, version) and a command like !1MVL3C\r (main volume to raw 0x3C, 30.0 on a 0.5-step model). Receivers also push status nobody asked for, so replies are matched by their 3-letter prefix and, for setters, by the echoed value. eiscp.py speaks the protocol, receivers.py decides which receiver a call means and serializes access to it, server.py holds the tools: each @mcp.tool() function's docstring becomes the description the model reads and its type hints the JSON Schema.

Verification status

Hardware-verified means seen on the owner's TX-NR6050 and/or TX-NR7100 (what was seen is in each assumption's note in src/onkyo_mcp/assumptions.py). Simulator-only means the simulator implements it and nothing has confirmed it.

O-MULTI-COMMAND is the one the restructure depends on most: tool calls used to open one connection per command, and now share one. doctor exercises it first (step 2). test_assumptions.py fails if this table and assumptions.py disagree.

Roadmap

• Zone 2 / Zone 3, inputs, listening modes, network services, stations, folders
• Several receivers by name; typed results; resources and prompts
• Streamable HTTP behind Cloudflare Access; OpenRC service on Alpine
• Hardware validation of the above (HARDWARE_VALIDATION.md)
• A persistent connection per receiver, with pushes as MCP resource updates (once the Claude apps support subscriptions)
• Publish to PyPI and the MCP registry

Acknowledgements

Command tables come from miracle2k/onkyo-eiscp, with corrections from the receivers themselves (their NRI lists TIDAL as 1B and AirPlay as 44).

License

MIT