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 (or, with Helper 5.0, a NESS / ELK M1 panel) 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)

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.

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:

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.

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 and live page navigation are UI features, not MCP tools. 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.