Metadata-Version: 2.4
Name: mcp-server-zwave-js-ui
Version: 0.3.0
Summary: MCP server for Z-Wave device management via the zwave-js-server WebSocket exposed by Z-Wave JS UI
Project-URL: Homepage, https://github.com/cacack/mcp-server-zwave-js-ui
Project-URL: Repository, https://github.com/cacack/mcp-server-zwave-js-ui
Project-URL: Issues, https://github.com/cacack/mcp-server-zwave-js-ui/issues
Author-email: Chris Clonch <cclonch@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: home-automation,mcp,smart-home,zwave,zwave-js
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.9
Requires-Dist: mcp>=1.0
Requires-Dist: zwave-js-server-python>=0.72
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-server-zwave-js-ui

An [MCP](https://modelcontextprotocol.io/) server for managing a Z-Wave network
through [Z-Wave JS UI](https://github.com/zwave-js/zwave-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-only.** This first release covers read-only
> introspection. Write control and administrative operations are on the
> roadmap — see [Roadmap](#roadmap).

## 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+**.

```bash
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

| Variable       | Default                 | Description                                  |
|----------------|-------------------------|----------------------------------------------|
| `ZWAVE_JS_URL` | `ws://localhost:3000`   | WebSocket URL of the Z-Wave JS Server.       |

## Use with Claude Code

```bash
claude mcp add zwave-js-ui \
  --env ZWAVE_JS_URL=ws://borg:3002 \
  -- uvx mcp-server-zwave-js-ui
```

Or add it to an MCP client config directly:

```json
{
  "mcpServers": {
    "zwave-js-ui": {
      "command": "uvx",
      "args": ["mcp-server-zwave-js-ui"],
      "env": { "ZWAVE_JS_URL": "ws://borg:3002" }
    }
  }
}
```

## Tools

| Tool                     | Description                                                        |
|--------------------------|-------------------------------------------------------------------|
| `zwave_controller_info`  | Controller and network summary (home id, versions, RF region, node counts). |
| `zwave_list_nodes`       | One-line summary of every node (status, readiness, security, device). |
| `zwave_node_info`        | Full detail for a node (device class, command classes, endpoints, signal). |
| `zwave_node_values`      | A node's current values, excluding configuration parameters.      |
| `zwave_node_config`      | A node's configuration parameters with current values and metadata. |

## Roadmap

- **Level 2 — read/write:** set values (on/off/dim), set configuration parameters, manage association groups. Mutating tools will be gated behind a `ZWAVE_JS_READ_ONLY` flag.
- **Level 3 — admin/lifecycle:** inclusion/exclusion, re-interview, network heal / rebuild routes, OTA firmware update.

## Development

```bash
git clone https://github.com/cacack/mcp-server-zwave-js-ui
cd mcp-server-zwave-js-ui
uv venv --python 3.13 && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
ruff check . && ruff format --check .
```

See [CLAUDE.md](CLAUDE.md) for architecture and design notes.

## License

[MIT](LICENSE)
