mcp-server-zwave-js-ui

An MCP server for managing a Z-Wave network through Z-Wave JS UI. It connects to the zwave-js-server WebSocket that Z-Wave JS UI exposes and surfaces the mesh — controller, nodes, values, and configuration parameters — as tools an MCP client (e.g. Claude) can call.

Status: early / read + write + lifecycle. Read-only introspection, write control (values, config parameters, node name/location, associations), and admin/lifecycle operations (re-interview, route rebuild, inclusion/exclusion, remove failed node) are available. Set ZWAVE_JS_READ_ONLY to hide every mutating tool and expose only the read tools. Triggering an OTA firmware update is still on the roadmap.

Quickstart

1. In Z-Wave JS UI, make sure the Z-Wave JS Server WebSocket is enabled (Settings → Home Assistant → WS Server; default port 3000). See What it connects to.

2. Add the server to Claude Code, pointing ZWAVE_JS_URL at that WebSocket. No manual install needed — uvx fetches and runs the published package:

   claude mcp add zwave-js-ui \
     --env ZWAVE_JS_URL=ws://<host>:3000 \
     -- uvx mcp-server-zwave-js-ui
   

3. Ask Claude about your mesh — it calls the read-only tools to answer:

   "Which Z-Wave controller am I running, and how many nodes are on the network?"

   "List my Z-Wave nodes and flag any that are dead or asleep."

For other MCP clients, isolated installs, and configuration details, see the sections below.

What it connects to

Z-Wave JS UI runs two servers: the web UI (default port 8091) and the Z-Wave JS Server WebSocket (default port 3000) that Home Assistant and this MCP server talk to. Point ZWAVE_JS_URL at the WebSocket, not the UI.

Install

Requires Python 3.12+.

pip install mcp-server-zwave-js-ui
# or, isolated:
pipx install mcp-server-zwave-js-ui
# or, no install:
uvx mcp-server-zwave-js-ui

Configure

Use with Claude Code

claude mcp add zwave-js-ui \
  --env ZWAVE_JS_URL=ws://<host>:3000 \
  -- uvx mcp-server-zwave-js-ui

Or add it to an MCP client config directly:

{
  "mcpServers": {
    "zwave-js-ui": {
      "command": "uvx",
      "args": ["mcp-server-zwave-js-ui"],
      "env": { "ZWAVE_JS_URL": "ws://<host>:3000" }
    }
  }
}

Tools

Write and admin tools (everything below the read-only rows) are hidden from the registry when ZWAVE_JS_READ_ONLY is set.

Read-only

Write control (level 2)

Admin / lifecycle (level 3)

Note on secure inclusion: interactive S2 security bootstrap (DSK/PIN grant) can't complete through this stateless server — use the Z-Wave JS UI for secure inclusion.

Roadmap

• Trigger OTA firmware updates. Reporting update status is available (zwave_firmware_update_status), but starting a flash streams progress events over minutes, which the per-call connection model can't observe within a single tool call; delivering it needs a persistent-connection design.

Development

git clone https://github.com/cacack/mcp-server-zwave-js-ui
cd mcp-server-zwave-js-ui
uv sync --extra dev            # create .venv from the checked-in uv.lock
uv run pytest
uv run ruff check . && uv run ruff format --check .

See CLAUDE.md for architecture and design notes.

License

MIT