nickol-knx-mcp

A design-time KNX / ETS6 assistant exposed as an MCP server.

It reads your .knxproj, analyzes group addresses / DPTs / topology, generates Home Assistant KNX YAML and ETS-importable group-address files (XML/CSV), and produces human-readable reports — without ever touching the live KNX bus.

🇷🇺 Русская версия: README.ru.md

🧪 Status & call for testers

This is a public beta. The full pipeline passes an end-to-end smoke test on a synthetic 16-group-address project, but it has had limited testing against real-world .knxproj files — and real ETS projects are wonderfully messy and diverse.

👉 If you have an ETS5/ETS6 project, please try it and tell us what happens. Open a Real-project test report issue. The tool is read-only and never connects to a bus, so testing is safe (see Safety model). See CONTRIBUTING.md for details.

Related MCP server: SDS MCP

Why this exists

As of mid-2026 there is no off-the-shelf ETS6 ↔ Claude / MCP tool. The KNX community has been explicitly asking for an integration that can inspect and help modify projects (adding / renaming devices and group addresses) through an AI/CLI workflow. This package fills exactly the design-time layer — the missing one.

The recommended full setup is four layers; only one needs to be built from scratch:

Safety by design: layer 2 (this server) physically cannot connect to a bus. It has no network/bus dependency at all — it only reads .knxproj and writes files into a confined workspace. The "never write to a live bus" requirement is enforced structurally, not by promise. Any real interaction with the house goes only through layer 1 (Home Assistant).

What the server does

• Parses password-protected ETS5/ETS6 .knxproj files via xknxproject (3.9.x).

• Extracts group addresses, DPTs, devices, topology, descriptions, and ETS Functions.

• Classifies every GA: category (lighting / shutter / hvac / sensor / scene / energy / diagnostics) and kind (command / status / sensor) — from the DPT plus multilingual (EN/DE/RU) keywords in the name.

• Validates naming against a 3-level structure and a configurable regex.

• Finds missing status addresses — primarily from ETS Function roles, falling back to name-token pairing (command in …/0/…, feedback in …/4/… is common, so it matches by name tokens rather than by middle-group adjacency).

• Catches DPT problems: missing DPT, mismatch between a Communication Object and its GA, and the same logical name carrying different DPTs.

• Generates Home Assistant KNX YAML — category by category, conservatively: covers → lights → switches → sensors/binary. Ambiguous items (e.g. DPT 5.001 — brightness vs blind position) are not guessed; they go into a review list instead.

• Generates ETS-importable group addresses in XML (the recommended knx.org/xml/ga-export/01 schema) and CSV (ETS's native layout).

• Writes a Markdown report (inventory + 🔴🟡🔵 findings + HA-mapping preview + next steps) for human review before any import.

All writes go only into the workspace directory (NICKOL_KNX_WORKSPACE, default ./knx-workspace); writes outside it are rejected.

Installation

Requires Python 3.10+.

git clone https://github.com/NickoScope/nickol-knx-mcp.git
cd nickol-knx-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Dependencies: mcp>=1.10, xknxproject>=3.8, PyYAML>=6.0.

On Debian/Ubuntu, if pip complains about an externally-managed environment, use a venv (as above) or pip install -e . --break-system-packages. If PyJWT conflicts, run pip install mcp --ignore-installed PyJWT first.

Verify:

python tests/test_pipeline.py     # synthetic 16-GA project, end-to-end smoke test
nickol-knx-mcp                    # start the MCP server (stdio)

Connecting to Claude

Claude Desktop

examples/claude_desktop_config.json wires up nickol-knx + filesystem + git + home-assistant. Minimal fragment (macOS config path: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nickol-knx": {
      "command": "nickol-knx-mcp",
      "env": { "NICKOL_KNX_WORKSPACE": "/path/to/your/knx-workspace" }
    }
  }
}

Claude Code

claude mcp add nickol-knx \
  -e NICKOL_KNX_WORKSPACE="$HOME/knx-workspace" \
  -- /absolute/path/to/.venv/bin/nickol-knx-mcp

Then drop CLAUDE.md into your project root — it acts as an ETS Assistant skill (design rules, safety rules, 3-level GA structure, command/status pairing, DPT discipline, naming, KNX Secure keyring handling, and the recommended workflow).

MCP tools (12)

Typical workflow

1. load_project → point it at your .knxproj (+ password if protected).

2. analyze_all or project_report → read the findings; human review first.

3. Fix naming/DPT/status in ETS (by importing generated GAs or manually).

4. generate_ets_group_addresses(fmt="xml") → import the missing GAs into ETS.

5. generate_ha_package → place the YAML into Home Assistant; resolve review items by hand.

6. Keep everything (.knxproj export, HA configs, address schema) in Git.

7. Touch the live house only through the Home Assistant MCP (layer 1).

Limitations (honest)

• command/status and category classification is a heuristic (DPT + names + ETS Functions). On messy projects with no Functions and non-standard names, false negatives/positives are possible — which is why the report is always for human review, and ambiguity goes to review, not into config.

• DPT 5.001 is structurally ambiguous (brightness vs position); it's disambiguated by keywords — double-check with non-standard naming.

• The HA generator is conservative: it would rather defer an item to review than emit a wrong entity.

• The server never writes to the bus and never talks to ETS directly — ETS exchange is file import/export of GAs only.

• Tested only on a synthetic project so far. Real .knxproj files vary a lot — hence the call for testers.

🔒 Safety model

• No bus access, structurally. There is no networking or bus library in the dependency tree. workspace_info() reports bus_access: false.

• Read-only on your project. project.py is the only module that touches .knxproj, and it only reads.

• Confined writes. All output is constrained to NICKOL_KNX_WORKSPACE; paths outside it are rejected.

• Human-in-the-loop. Generate a project_report and review it before importing into ETS or deploying into Home Assistant.

Found a security issue? See SECURITY.md.

Package layout

nickol-knx-mcp/
├── nickol_knx_mcp/
│   ├── dpt_map.py        # DPT → category / kind / HA platform / value_type
│   ├── project.py        # the ONLY module that reads .knxproj (read-only)
│   ├── pairing.py        # command↔status pairing by name tokens
│   ├── analyze.py        # naming / missing-status / DPT checks
│   ├── generate_ha.py    # Home Assistant KNX YAML generation
│   ├── generate_ets.py   # ETS XML + CSV generation
│   ├── report.py         # Markdown report
│   └── server.py         # FastMCP server, 12 tools, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── CLAUDE.md             # ETS Assistant skill / playbook
├── pyproject.toml
└── README.md

Contributing

Testers and contributors are very welcome — especially real-project test reports. See CONTRIBUTING.md and the issue templates.

License

MIT © 2026 Nikolay Miroshnichenko

Not affiliated with or endorsed by the KNX Association. "KNX" and "ETS" are trademarks of the KNX Association cc. This is an independent, community tool.