Skip to content

About

MCP server for the Logitech Harmony Hub universal remote platform.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

mcp-server-harmony

CI

An MCP server for Logitech Harmony Hubs, one or many (say, one per TV). It talks to each hub directly over its local websocket API, with no Home Assistant and no Logitech cloud. It lets an MCP client such as Claude start and stop activities, press buttons, and read what's on. It works with any remote paired to a hub (Elite, Companion, 950), since the server talks to the hub, not the remote.

Status: alpha, looking for testers. Run on two Harmony Hubs (2026-10-14, 2026-11-04 and 2026-11-12): connecting, status and names, starting and switching activities, button presses (routed through the running activity and sent to a named device), power off on one hub and on all, the busy guard, an activity renamed in the Harmony app showing up without a restart, the activity expected state (fixit) against the app, channel digits on one LG TV, the sleep timer, and the activity history. Still simulator-only: SSDP discovery, the exact frames of a start and a press, held buttons, and re-reading state after a reconnect. Not yet tried on hardware: favorites, channel entry on the Bedroom Hub or a set-top box, and a start from the remote's own button for history. Every protocol detail is a named assumption (see Verification status), and HARDWARE_VALIDATION.md is the checklist for confirming them. If you have a hub, a hardware report of what worked on yours is the most useful thing you can send.

Not affiliated with Logitech. Built on aioharmony, the library behind Home Assistant's Harmony integration.

Design: activity-first

A Harmony is built around activities ("Watch Shield", "Listen to Music"): starting one powers the right devices and sets their inputs. That's also the right level for a model:

  • harmony_start_activity("Watch Shield") is one call; the hub handles the device choreography.
  • harmony_send_command("VolumeUp") with no device goes through the running activity, so volume reaches the receiver and Pause reaches the Shield without the model knowing your wiring.
  • harmony_send_command(device="Onkyo AV Receiver", ...) is there for the cases activities don't cover.

Several hubs

One server drives all your hubs, each by its own name (the one set in the Harmony app). Tools take an optional hub, and the model only needs it when a name is ambiguous:

  • Unique names just work. harmony_start_activity("Watch TV") finds the one hub that has it.
  • A repeated name asks. If both hubs have "Listen to Music", the tool returns an error naming both hubs, and the model asks you or retries with hub.
  • Hub-qualified refs. The list tools return a ref such as "Den/Listen to Music", which works anywhere a name does, so the model can copy one string.
  • Buttons follow the running activity, when exactly one hub has one running. With both TVs on, harmony_send_command("VolumeUp") asks which.
  • harmony_power_off turns off the one hub that's on, asks if several are, and takes hub="all" for every one. With all, each hub is reported separately, so one unreachable hub doesn't stop the others. force=true is the escape hatch for a hub stuck mid-sequence: it sends the power off even while busy (see Safety design).

The server never guesses between hubs: each one is a different TV, and a guess turns off the wrong room.

Sleep timer

"Turn the bedroom TV off in 45 minutes" is harmony_set_sleep_timer(minutes=45). A model only acts when it is called, so the server, which is long-lived and holds the hub connection, keeps the timer.

  • It runs the same power off as harmony_power_off, so the busy guard, the rate limit and dry run apply. If the hub is mid-sequence or unreachable when it fires, it retries every 15 s for 5 minutes, then gives up and keeps the reason.
  • With no hub, exactly one hub must be on (the harmony_power_off rule). A hub that is off is refused. minutes=0 cancels (with no hub, the one hub that has a timer). A new timer replaces the old one.
  • The hub being powered off before it fires, by anyone, drops the timer. Switching activities keeps it.
  • Nothing can notify the model when it fires, so harmony_get_status shows each hub's sleep_timer (fires_at, minutes_left, retrying) while pending and last_sleep_timer (fired, cancelled or failed, and why) afterwards.
  • It lives in this server's memory only, and is not saved. Under serve --http it outlives the chat; over stdio the server exits when the MCP client closes, and the timer goes with it. A TV that turns itself off after a restart, long after anyone remembers asking, is worse than a lost timer.

Install

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

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

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

Requires Python 3.11+.

First contact

There's no pairing: a hub's local API answers anything on the LAN at TCP 8088.

mcp-server-harmony discover                       # SSDP: lists hubs that answer
mcp-server-harmony check --discover               # ...and adds them all
mcp-server-harmony check --host 192.168.1.60      # or one at a time, by IP
mcp-server-harmony doctor                         # each hub, layer by layer, with hints
mcp-server-harmony call start_activity activity="Den/Watch TV"     # one tool, as the model calls it

check connects, prints the hub's name, activities and devices (the exact names the model will use), and adds the hub to ~/.config/mcp-server-harmony/config.json with its name. Plain check rechecks every configured hub. SSDP is multicast, so it doesn't cross VLANs or guest networks; --host always works.

doctor checks TCP, provisioning, the websocket and the catalog for each hub, and warns about activity names that more than one hub has. doctor --dump DIR saves a redacted copy of each hub's config for tests/fixtures/recorded/.

Export your setup

Logitech stopped making Harmony in 2021, and a hub can only be set up through Logitech's cloud, so your setup (devices, what each activity turns on and which input it picks, where each button goes) lives only on the hub and in that cloud. export writes it down:

mcp-server-harmony export                       # every configured hub, into export/ in the config folder
mcp-server-harmony export --dir ~/harmony --host 192.168.1.60 --redact

For each hub it writes two files, readable by you only:

  • <hub>.json: the hub's full config as it returned it, with Logitech account identifiers removed (the same scrub as doctor --dump). Addresses stay in, since this is your own record; --redact masks IPs and MACs for sharing.
  • <hub>.md: a worksheet for rebuilding the setup on another remote (Sofabaton, Unfolded Circle, Home Assistant, ...): a devices table, then each activity with every device's expected power and input and which device gets each group of buttons, then every device's command names.

What it is not: a backup. The hub's local API returns command names, not the IR codes behind them, and nothing can be written back to a hub. It is a record to rebuild from: the new remote finds each device in its own database by manufacturer and model, or learns the codes from your Harmony remote. Expected power and input come from each activity's fixit data (H-FIXIT); where an activity has none, the worksheet says unknown.

Use it with an MCP client

Local (stdio): Claude Code and Claude Desktop launch it themselves. With uv installed, uvx fetches and runs the published package, so there's no venv to manage. In Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "harmony": { "command": "uvx", "args": ["mcp-server-harmony"] }
  }
}

Or point command at the venv you installed into (~/.venvs/harmony/bin/mcp-server-harmony; on Windows, ...\Scripts\mcp-server-harmony.exe). Run check first (uvx mcp-server-harmony check --host <ip>): the server reads the hubs from its config.json, so the client config needs no settings. Alternatively, pass the hub addresses directly in the client config with "env": {"HARMONY_HOSTS": "192.168.1.60,192.168.1.61"}. Claude Desktop doesn't see your shell's PATH, so if it can't start uvx, give its full path (which uvx, or where uvx on Windows).

For Claude Code: claude mcp add harmony -- uvx mcp-server-harmony.

Things you can ask:

  • "What's on in the living room?"
  • "Start Watch Shield in the den and turn the volume down 3 steps."
  • "Tune the living room TV to ESPN" (or "tune to 9.1").
  • "Turn the bedroom TV off in 45 minutes."
  • "How long was the office TV on today, and was it turned on from the remote?"
  • "I'm moving to a Sofabaton X2 — write a checklist for rebuilding all my Harmony activities there."

As a service (Streamable HTTP), to share one instance between Claude Code, Claude Desktop and the mobile app through a Cloudflare Tunnel with Cloudflare Access in front:

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

GET /healthz answers 200 while at least one hub is connected and 503 when none is (or before the server has started), for a load balancer or supervise-daemon check. It doesn't contact the hubs, and it's answered before the Access check, so its body is only {"status": ...}.

Every request must carry a valid Access JWT (Cf-Access-Jwt-Assertion). The checks and the flags are documented in src/harmony_mcp/remote.py. The Host-header (DNS-rebinding) checks stay on even with --bind 0.0.0.0: for LAN clients, also pass --public-host <this machine's LAN IP>.

As an OpenRC service on Alpine (e.g. a Proxmox LXC)

deploy/alpine/ installs it the same way as mcp-server-webos, so the two can share an LXC: a venv in /opt/mcp-server-harmony, a mcp-harmony system user, settings in /etc/mcp-server-harmony/env, the hub list in /var/lib/mcp-server-harmony/config.json, and supervise-daemon restarting it if it exits. The LXC needs TCP 8088 to each hub.

git clone https://github.com/SDNick484/mcp-server-harmony.git && cd mcp-server-harmony
sh deploy/alpine/install.sh                                # as root; re-run to upgrade
su -s /bin/sh mcp-harmony -c 'HARMONY_CONFIG_DIR=/var/lib/mcp-server-harmony \
  /opt/mcp-server-harmony/venv/bin/mcp-server-harmony check --host <hub ip>'    # once per hub
vi /etc/mcp-server-harmony/env                             # public host and Access settings
rc-update add mcp-server-harmony default && rc-service mcp-server-harmony start

Logs are in /var/log/mcp-server-harmony/server.log. CI runs deploy/alpine/smoke-test.sh in a stock python:3.12-alpine container: install, the test suite on musl, the service under OpenRC, and an MCP call over HTTP reaching a simulated hub.

Configuration

Setting Default What it does
HARMONY_HOSTS (from config.json) Comma-separated hub addresses; replaces the file's list
HARMONY_CONFIG_DIR $XDG_CONFIG_HOME/mcp-server-harmony Where config.json lives
HARMONY_DRY_RUN off Read the hubs, send nothing that changes anything (serve --dry-run too)
HARMONY_LOG_UNREDACTED off Don't mask IPs and MACs in logs (--no-redact); secrets stay masked
HARMONY_HISTORY on off stops recording activity changes (see Activity history); beats "history" in config.json

config.json (written by check, safe to edit by hand):

{
  "hubs": [
    { "host": "192.168.1.60", "name": "Living Room" },
    { "host": "192.168.1.61", "name": "Den" }
  ]
}

name is optional: without it, the hub's own name is used once it connects. Write your own to call a hub something else; check fills in missing names but never replaces one. A hub also answers to its address. Optionally add "protocol": "WEBSOCKETS" (or "XMPP") to skip the transport race. HARMONY_HOST (one hub) and the older {"host": ...} form still work. Problems (a host with a port, duplicate hosts or names, invalid JSON) are reported by name at startup and by doctor. "history": false turns off the activity history (or HARMONY_HISTORY=off).

Channel favorites. A hub may also have a channels map, a name for each channel number harmony_tune_channel can press (lineups differ per TV provider, so they belong to a hub):

{ "host": "192.168.1.60", "name": "Living Room", "channels": { "ESPN": "702", "KQED": "9.1" } }

Numbers are strings of up to 6 digits with at most one - or .; a bad entry is skipped and reported like any other config problem. check keeps the map when it rewrites the file, and harmony://hubs/{hub} shows it.

Tools

Tool What it does
harmony_get_status Start here: every hub's name, reachable, firmware, on/off, running activity, and any transition
harmony_list_activities Activities on each hub, with ref, marking the running ones
harmony_list_devices Devices on each hub, with ref, manufacturer, model and command count
harmony_list_commands Commands for an activity or device (default: the running activity), and which device gets each
harmony_start_activity Start an activity and wait until its hub finishes; unchanged if it's already running
harmony_power_off Run a hub's power-off (or hub="all"); unchanged if it's already off; force sends it anyway
harmony_send_command Press a command 1-10 times (repeat), optionally held (hold_ms) or spaced (delay_ms)
harmony_describe_activity Read-only: the devices an activity involves with expected power (on/off/unknown) and input, and which device gets each button group
harmony_set_sleep_timer Turn a hub's TV system off in 1-720 minutes (minutes; 0 cancels); a new one replaces the old; see Sleep timer
harmony_tune_channel Press a channel number (702, 5.1, 5-1) or a favorite's name as one digit sequence; enter adds a select press
harmony_get_history What each hub's activity changed from and to, and when, newest first (or after_seq to catch up)

Every tool except harmony_get_status takes an optional hub. Actions return {hub, outcome: done | unchanged | dry_run | error, detail, sent}, where sent lists the frames that went to the hub. The server also offers resources (harmony://hubs, harmony://hubs/{hub}) with each hub's catalog, a fix_stuck_remote prompt for the Shield's Bluetooth keyboard getting stuck, and a migrate_to_another_remote(target) prompt that describes every activity and writes a rebuild checklist for the remote you name (the chat version of export).

There is deliberately no tool that returns a hub's raw config: it is tens of kilobytes that a model has no use for. harmony_describe_activity returns the part that matters, and export writes the whole config to a file.

harmony_describe_activity reads each activity's fixit data from the hub's config (H-FIXIT, checked against the Harmony app on two activities, firmware 4.15.600). When an activity has none, it says expected_state: "unknown" and reports power as unknown rather than guessing.

A session against the simulator

Two hubs that both have "Listen to Music". (Output from simulate, trimmed.)

> harmony_get_status
  {"dry_run": false, "hubs": [
    {"hub": "Living Room", "reachable": true, "power": "off", "current_activity": null, "transition": null, ...},
    {"hub": "Den", "reachable": true, "power": "off", "current_activity": null, "transition": null, ...}]}

> harmony_start_activity {"activity": "Listen to Music"}
  ERROR: Activity 'Listen to Music' exists on Living Room, Den; pass hub to choose.

> harmony_list_activities {"hub": "Den"}
  [{"hub": "Den", "name": "Watch TV", "ref": "Den/Watch TV", "running": false},
   {"hub": "Den", "name": "Listen to Music", "ref": "Den/Listen to Music", "running": false}]

> harmony_start_activity {"activity": "Den/Listen to Music"}
  {"hub": "Den", "outcome": "done", "detail": "Start Listen to Music on Den",
   "sent": ["runactivity activityId=39000002 (Listen to Music)"]}

> harmony_start_activity {"activity": "Watch Shield"}
  {"hub": "Living Room", "outcome": "done", "detail": "Start Watch Shield on Living Room", ...}

> harmony_send_command {"command": "VolumeUp", "repeat": 3}
  ERROR: Activities are running on Living Room (Watch Shield), Den (Listen to Music); pass hub to choose.

> harmony_send_command {"command": "VolumeUp", "hub": "Living Room", "repeat": 3}
  {"hub": "Living Room", "outcome": "done", "detail": "Send VolumeUp x3 to Onkyo AV Receiver on Living Room",
   "sent": ["holdAction press+release Onkyo AV Receiver/VolumeUp", ...]}

> harmony_power_off
  ERROR: Several hubs are on (Living Room, Den); pass hub, or hub='all' for every one.

> harmony_power_off {"hub": "all"}
  {"results": [{"hub": "Living Room", "outcome": "done", "detail": "Power off Living Room", ...},
               {"hub": "Den", "outcome": "done", "detail": "Power off Den", ...}]}

Activity history

harmony_get_history(hub, limit, after_seq) answers "what was on at 9 last night?", "how long was the office TV on today?" and "did someone turn the bedroom TV on from the remote?". The hub pushes every activity change over the websocket this server already holds open, including ones made with the physical remote or the Harmony app, and the server keeps them. It is the counterpart of sofabaton_get_recent_presses: newest first, or oldest first after after_seq, with last_seq to poll from.

Each change records when (UTC), the hub, what it changed from and to (null is everything off), how long the previous state lasted, and where it came from. source is this_server for a start or power off this server sent and elsewhere for everything else (the remote, the Harmony app, Home Assistant); the hub doesn't say who asked, so those three can't be told apart. A change found only by re-reading the state after a reconnect is marked noticed_late: it happened at an unknown time while the socket was down, and at is when it was noticed.

The first state read after the server starts is not a change. It is recorded as recording_started with that state, so a gap reads as "not recorded" and not "nothing happened". Over stdio the server only runs while the MCP client does, so those gaps are normal. previous_lasted_at_least is true when the previous state began before recording did, so its duration is a minimum.

mcp-server-harmony call only reads the history: call get_history shows what a server recorded, but a call never adds to the file, not even the recording_started marker (otherwise a few call get_status runs would fill it with markers). serve (stdio and --http) records as above. If a server is running, a change a call makes is pushed to it by the hub and recorded there as elsewhere, so it is not written twice. A call made while no server runs leaves no record. Because a server may be appending while a call reads, a half-written last line is skipped, never an error.

Safety design

  • The hub's own config is the allow-list. Activity, device and command names are resolved against what the hub already knows. There's no way to send a raw IR code, an unknown device id, or a command from one device to another.
  • Left out on purpose: sync (talks to Logitech's cloud), the hub's change_channel engine command, and anything that edits the hub's configuration. Tuning works by digit presses (harmony_tune_channel), each one a command the hub's config already lists and resolved through the catalog like any other press, so the allow-list still bounds it; change_channel would hand the hub a free-form channel and skip that.
  • No interleaving with activity sequences. While a hub is starting an activity or powering off, its commands are refused with "busy, try again", since a press mid-sequence can land on a device that's still warming up. The one exception is harmony_power_off(force=true), for a sequence that never finishes (a device that never answers its warm-up): it skips this server's own busy guard and sends the power off anyway. It still counts against the rate limit, and with no hub it only acts on hubs that are on or mid-sequence. The hub itself can still say no: on a real hub a forced power off during a normal start was refused with "Activity in progress", just as the physical remote ignores Off then (H-FORCE-OFF, hardware-contradicted). Whether force helps a hub that is truly stuck hasn't been tested.
  • Rate limits and caps, per hub. Per call: at most 10 repeats, held up to 3 s, 100-2000 ms apart, 15 s in total. Across calls (a model in a loop): 20 presses in a burst, then 4 a second; 4 activity changes in a burst, then one per 15 s. A call over the limit is refused whole, never half-sent. A channel number is one sequence of up to 8 presses, 400 ms apart, charged and refused as a whole.
  • Activity history is a record of viewing habits, kept on your own disk. It stores, per change: the time, the hub's name, the activity names before and after, how long the previous one lasted, and whether this server or something else caused it. No addresses (a hub known only by its address is stored masked, x.x.x.20), no commands, no device names. It is held in memory (the newest 1000 events) and appended to history.jsonl in the config directory (HARMONY_CONFIG_DIR, by default ~/.config/mcp-server-harmony), which is created readable by you only (mode 0600) and trimmed to the newest events. To turn it off, set HARMONY_HISTORY=off or "history": false in config.json: nothing is then recorded, in memory or on disk, and harmony_get_history says so. To forget what was kept, delete the file. If the file can't be written (a read-only disk), that is logged once and history carries on in memory.
  • Dry run. serve --dry-run (or call --dry-run) reads the hubs and reports what it would send.
  • Resilient. Each hub reconnects with backoff, and re-reads its state after a reconnect. If the connection task itself crashes, it's logged and restarted (also with backoff) instead of leaving the hub offline until the server restarts. An offline hub doesn't block the others, and shutdown is bounded per hub.
  • Logs are redacted: IP addresses and MACs (unless --no-redact), and always secrets (JWTs, bearer tokens, keys, URL passwords). They go to stderr; stdout is the MCP transport.
  • Every tool carries a title and MCP annotations. Nothing is marked destructive (activities and button presses change what's on, not data). harmony_send_command is non-idempotent, since VolumeUp twice is +2.

Troubleshooting

Message Meaning
No Harmony hub configured. Run check --host <ip> once per hub, or set HARMONY_HOSTS (in the client's config)
Can't reach the Harmony hub 'Den' at ... Offline, its IP changed, or TCP 8088 is blocked (a VLAN in between). Other hubs keep working
... exists on Living Room, Den; pass hub to choose. The name is on more than one hub: the model should ask which TV, or use a ref
Den is busy starting ... An activity is mid-sequence. Wait until harmony_get_status shows transition: null; if it never clears, harmony_power_off(force=true) (the hub may still refuse a power off mid-start, "Activity in progress")
Rate limit: refusing to ... Many presses in a short time. Wait and retry if it was deliberate

doctor says which layer failed for each hub and what to check.

Development

pip install -e ".[dev]"
pytest -q           # everything, no hardware: real aioharmony against fake hubs over real sockets
ruff check . && ruff format --check . && mypy

The simulator runs the same fake hubs as real services on 127.0.0.1 and 127.0.0.2:

mcp-server-harmony simulate --write-config /tmp/hcfg     # two hubs; --hubs 1 for one, --flaky N to drop connections
HARMONY_CONFIG_DIR=/tmp/hcfg mcp-server-harmony doctor

(On macOS, add the second loopback address first: sudo ifconfig lo0 alias 127.0.0.2.)

What the tests cover:

File Covers
test_contract.py The real aioharmony against the fake hub over a socket: the wire protocol, faults, reconnects
test_catalog.py Parsing a hub's config into the allow-list
test_client.py One hub: start, power off, presses, the busy guard
test_multi_hub.py Several hubs: ambiguity, refs, an offline hub, partial failures
test_tools.py The MCP contract the model sees (schemas, annotations, structured results)
test_safety.py Dry run, rate limits, caps, config validation, shutdown
test_sleep_timer.py The sleep timer: firing, replace, cancel, retries, dropping, shutdown, several hubs
test_tooling.py doctor, discover, call, simulate, log redaction
test_recorded.py Replays configs captured from real hubs (doctor --dump)
test_assumptions.py Every assumption appears here and in HARDWARE_VALIDATION.md
test_export.py export against the fake hub: both files, owner-only, no account identifiers, --redact
test_channels.py Tuning: channel numbers, favorites, the digit sequence, and the -/. lookup fix

Verification status

These are the protocol assumptions the code depends on (claim, source, and for verified ones the evidence, in src/harmony_mcp/assumptions.py). hardware-verified means seen working on a real hub; hardware-contradicted means a real hub did something else; the rest are verified against the simulator only:

Assumption Confidence Status
H-PORT high hardware-verified
H-PROVISION high hardware-verified
H-FRAMES high hardware-verified
H-CONFIG-SHAPE high hardware-verified
H-POWEROFF high hardware-verified
H-NAME high hardware-verified
H-START-SEQUENCE medium simulator-only
H-FORCE-OFF low hardware-contradicted
H-PRESS-SILENT medium simulator-only
H-PRESS-ERROR low simulator-only
H-HOLD low simulator-only
H-CONFIG-PUSH medium hardware-verified
H-RECONNECT high simulator-only
H-SSDP medium simulator-only
H-TIMING low simulator-only
H-FIXIT medium hardware-verified
H-DIGITS medium hardware-verified
H-ACTIVITY-PUSH medium hardware-verified
H-OFF-PUSH low hardware-verified

"High" means aioharmony itself depends on it, and Home Assistant's Harmony integration runs on aioharmony. test_assumptions.py fails if this table and assumptions.py disagree.

Roadmap

  • Validate on hardware (HARDWARE_VALIDATION.md)
  • Surface activity changes as MCP resource updates, once the Claude apps support subscriptions
  • Publish to the MCP registry

License

MIT. See LICENSE.

About

MCP server for the Logitech Harmony Hub universal remote platform.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages