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.
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.
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
refsuch 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_offturns off the one hub that's on, asks if several are, and takeshub="all"for every one. Withall, each hub is reported separately, so one unreachable hub doesn't stop the others.force=trueis 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.
"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 (theharmony_power_offrule). A hub that is off is refused.minutes=0cancels (with nohub, 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_statusshows each hub'ssleep_timer(fires_at,minutes_left,retrying) while pending andlast_sleep_timer(fired, cancelled or failed, and why) afterwards. - It lives in this server's memory only, and is not saved. Under
serve --httpit 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.
python -m venv ~/.venvs/harmony && . ~/.venvs/harmony/bin/activate
pip install mcp-server-harmonyFrom 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]" && pytestRequires Python 3.11+.
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 itcheck 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/.
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 --redactFor 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 asdoctor --dump). Addresses stay in, since this is your own record;--redactmasks 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.
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/mcpGET /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>.
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 startLogs 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.
| 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.
| 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.
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", ...}]}
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.
- 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'schange_channelengine 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_channelwould 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 nohubit 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). Whetherforcehelps 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 tohistory.jsonlin 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, setHARMONY_HISTORY=offor"history": falseinconfig.json: nothing is then recorded, in memory or on disk, andharmony_get_historysays 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(orcall --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_commandis non-idempotent, since VolumeUp twice is +2.
| 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.
pip install -e ".[dev]"
pytest -q # everything, no hardware: real aioharmony against fake hubs over real sockets
ruff check . && ruff format --check . && mypyThe 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 |
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.
- Validate on hardware (HARDWARE_VALIDATION.md)
- Surface activity changes as MCP resource updates, once the Claude apps support subscriptions
- Publish to the MCP registry
MIT. See LICENSE.