Myro:Home Helper MCP server

Lets an AI assistant (Claude Desktop, Claude Code, ChatGPT desktop, anything that speaks MCP) read and control an HAI / Leviton Omni controller, a NESS / ELK M1 panel, a Savant system (preview), or a Control4 system through Control4 Link (preview, Helper 5.50), through Myro:Home Helper, using the Helper's HTTP API. The assistant sees typed tools with descriptions instead of guessing URL shapes.

What you need

• Myro:Home Helper (Mac App Store) 4.06 or later on a Mac on your network (4.07 or later for the read tools: list_objects, get_object, helper_log).
• An API key for your controller: Helper → API tab → Generate.
• uv on the machine running the assistant (brew install uv or the one-line installer). uvx fetches and runs this server on demand and keeps it updated.

NESS / ELK

Helper 5.0 adds NESS / ELK M1 panels alongside HAI / Leviton Omni. The tools and their parameters are the same for both; controller_status reports controllerFamily ("HAI / Leviton" or "NESS / ELK", derived from the controller's protocol), and the live scripting_reference is scoped to that family, so the assistant should read it before writing scripts. On ELK, user codes may be 4 or 6 digits (security-code set accepts either), there is no energy-cost level, and audio is a legacy M1XEP integration.

Savant (preview) and Control4 Link (preview, Helper 5.50)

Savant and Control4 are room and activity systems, not alarm panels. They have no zones, units, arming or panel messages, so the panel tools (set_unit, arm, set_thermostat and the rest) do not apply to them.

• controller_status reports controllerFamily "Savant" or "Control4", plus backend, rooms, roomStates, inventory, homeKit, objectCounts and capabilities. Unknown room fields are omitted rather than guessed.
• Automate them through scripts. Read scripting_reference first (it is scoped to the selected controller and lists the real rooms, activities and services), then validate_script and save_script (saved disabled). Savant scripts use MyroSavant; Control4 scripts use MyroControl4. Saving and enabling need an API key with remote script management.
• Sign-in credentials for either system live only in Helper's Connection pane, never in MCP or a conversation.

Compatibility

A tool that needs a newer Helper than the one running answers with requiredHelper instead of failing silently.

Configure

Claude Desktop (claude_desktop_config.json) or any client that takes the standard MCP config:

{
  "mcpServers": {
    "myrohome-helper": {
      "command": "uvx",
      "args": ["myrohome-helper-mcp"],
      "env": {
        "MHH_URL": "http://192.168.1.76:9393",
        "MHH_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code:

claude mcp add myrohome-helper -e MHH_URL=http://192.168.1.76:9393 -e MHH_API_KEY=your-api-key -- uvx myrohome-helper-mcp

The controller ID is fetched from the Helper automatically. Set MHH_CONTROLLER_ID only if you want to pin it.

Tools

Read:

Door access (HAI / Leviton)

An access-control reader and the lock it releases share one number. list_objects("Access Control Lock") and get_object("Access Control Lock", n) return locked and, once the reader has reported, the last access:

Access Control Reader objects carry the same result as granted, lastUser and lastAccessAt. The panel does not timestamp accesses, so lastAccessAt is "last reported", not necessarily the moment of the swipe. Helper 5.01 and later read reader status at startup and on every status refresh; older Helpers report it only after the next badge or keypad code. User codes are never exposed. Reading door access is a read: it adds no write tool, and unlocking stays behind the owner opt-in below.

The new history/activity tools require adapter 0.4.0 and Helper 4.50. Panel event dates contain no year; receivedAt is download time, not event time. History indexing is incremental: retry when indexing is true. HVAC intervals are estimates from reported action, and unknownSeconds must not be interpreted as equipment being off. These additions do not change the existing security tools. Recent event refreshes are limited to once every 30 seconds per controller; full downloads to once every 10 minutes. A 429 means wait and use the cached panel_events result, not repeat the download immediately.

Write (each changes the physical home; tool descriptions tell the assistant to confirm first):

Adapter 0.5.0 adds typed /control tools for blinds, thermostats, area lights, buttons, UPB links, messages, locks, user settings and audio transport, plus timers on units, flags and outputs (Helper 4.07 or later). Existing untimed unit/flag/output, audio, energy, notification, speech, log and sync tools retain their existing routes. Timed dim levels, intermediate blind positions and flag counters are rejected because the panel ignores their timer. Thermostat setpoints use the controller's temperature format; Helper enforces that format's range. A controller ACK means acceptance, not physical completion. After an error or timeout, read the state before considering another write; commands are never automatically retried.

Timeline notes (Helper 5.50+; a note is a line in the home Timeline, not a physical action: it never notifies, never takes a picture and never sends a command):

Helper allows 120 notes and moments an hour per API key (429 past that) and refuses a bad value with one sentence (400). The tool descriptions tell the assistant to say what it wrote. Notes cannot be changed or deleted through MCP, and the scripting rules that quiet or rename automatic Timeline events (MyroTimeline.mute, rename, mode) have no MCP form; a script saved with save_script can set them.

Scripts (save, enable and reload need a key with remote script management enabled; listing, reading and validating do not):

Helper 4.50 relative controls

Adapter 0.5.0 adds the four relative tools above, requiring an updated Helper 4.50 build with these actions. Earlier 4.50 builds may not support them. Discover the exact Flag or Unit number first. They validate input locally and use the authenticated typed control endpoint; the Helper also checks that the object has the right type. Each counter call requests one step. Lighting steps are not percentage points; device support and resulting levels depend on the panel and lighting technology. The panel defines behavior at counter endpoints 0/255. Flags can trigger panel programs, so confirm intent before changing them.

No automatic retries: an ACK timeout may mean the command already applied. accepted means the panel acknowledged it, not that a particular final value was observed. Check reported state after uncertainty. These additions do not expand security permissions. Older Helpers return explicit failure with an updated 4.50 build requirement; the adapter never substitutes a cached-value write.

Helper 4.50 scripting features

The live scripting_reference exposes MyroLibraries, MyroControllers, and MyroSystem.speakQueued / cancelSpeech / cancelAllSpeech. MCP can generate, validate and save scripts using these APIs through the existing script tools; it does not need a separate tool for every JavaScript method.

Library files must be installed locally in Helper's Scripts/Libraries folder. Cross-controller access requires local Send To and Accept From grants at the respective controllers. MCP cannot upload library files, change grants, or silently switch its controller API key. A grant extends the origin scripts' authority, including remotely managed scripts, so enable it only deliberately. Validation checks the script body without loading dependencies or proving permissions, device state or speech playback. Save disabled and review before enabling. Script-owned speech cancellation does not cancel the separate HTTP speech queue used by MCP's speak tool.

Browser login, themes, live page navigation, Apple TV pairing, doorbell marking, the home history, the Timeline (and its kept doorbell and camera pictures) and UniFi Protect camera setup and events are UI and browser-session features, not MCP tools: they are served under /helper/web/* for a signed-in browser, or under /helper/timeline for a paired app's session token, and the MCP API key cannot use them. MCP reads only the results an API key can reach: list_favorites, the doorbell field that list_objects and get_object carry on marked zones, flags and outputs (list_doorbells filters to them), web_capabilities, which reads the public controller list the web control and Myro:Home Pro for Apple TV use (no sign-in; only this controller's entry is returned), suggestions, the household's usage-ranked Suggestions list (GET /helper/{controllerID}/suggestions; the usage events themselves, their upload and their deletion stay with the paired apps and the browser's Clear usage history), and since 0.8.0 the Timeline itself through its keyed routes: timeline reads GET /helper/{controllerID}/timeline (moments and events, never the pictures) and timeline_note and timeline_moment write through POST /helper/{controllerID}/timeline/notes. UniFi Protect sign-ins never pass through MCP. History queries include archived data automatically; archive deletion policy remains local configuration, not an MCP write capability.

Audio, Lutron and displays:

Helper Mac:

Security (all three need an API key with arm/disarm enabled; arm also needs a panel code stored locally):

arm stays disabled until the owner stores a panel code on the machine running this server. bypass_zone and restore_all_zones work without one on Helper 4.13 or later, running as the panel's Programmed user; with a stored code they run as that user instead. To store or remove the code:

uvx myrohome-helper-mcp security-code set      # prompts; nothing is echoed
uvx myrohome-helper-mcp security-code delete

The code goes into the operating system credential store (macOS Keychain, Windows Credential Locker, Linux Secret Service) under the controller's identity. It is never placed in the MCP config, an environment variable, or a conversation, and it is read only when a security tool is actually called. Helper validates it against the panel itself.

Disarming and unlocking (off by default)

An assistant cannot turn the alarm off or unlock a door unless you allow it, on the computer running this server:

uvx myrohome-helper-mcp allow disarm        # adds the disarm tool
uvx myrohome-helper-mcp allow unlock        # adds the unlock_door tool
uvx myrohome-helper-mcp disallow disarm     # takes it away again

Each asks you to type the word to confirm, and applies only to the controller that API key belongs to. Restart your MCP client afterwards. Until you allow them, the tools are not registered at all, so an instruction hidden in an email, web page or document the assistant reads has nothing to call. Disarm still also needs an API key with arm/disarm enabled and a stored panel code. Revoking takes effect on the next call, without a restart.

AI assistants can be misled by text they read. Allow these only if you understand that, and prefer the Myro:Home app for disarming.

Security

This server runs on your LAN like every other Myro:Home client and holds one controller's API key. Anyone who can run the assistant with this config can do what the key allows. Keep it on trusted machines. The Helper's HTTP API is plain HTTP on the local network; do not expose port 9393 to the internet.

Developing

uv sync
MHH_URL=http://192.168.1.76:9393 MHH_API_KEY=... uv run myrohome-helper-mcp   # stdio server
uv run mcp dev src/myrohome_helper_mcp/server.py                             # MCP inspector

Releasing

Bump version in pyproject.toml and __init__.py, commit, then tag and push: git tag v0.1.0 && git push origin v0.1.0. The GitLab CI job builds and publishes to PyPI through trusted publishing (one-time setup: PyPI project -> Publishing -> add GitLab publisher MyroControl/myrohome-helper-mcp, environment pypi).

MIT licensed. Myro Control, LLC.