nickol-knx-mcp

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

Four things you can do with it — all without ever touching the live KNX bus:

1. Design a project from a spec — turn an equipment list / project specification into a complete, validated group-address structure plus the full implementation document set (ETS-importable XML/CSV, human-readable report, Home Assistant YAML, acceptance test protocol, as-built handover pack).
2. Audit, repair & finish an existing project — validate naming · DPT & sub-DPT · command↔status · KNX Secure · Matter-readiness, get concrete fix proposals (inferred DPTs, synthesised status GAs), grade completeness, and diff two project versions.
3. Generate the smart-home layer — assembled Home Assistant entities (colour lights, climate, covers, sensors) that read real device state, with everything ambiguous deferred to human review.
4. Compose a new project from parametrised room templates — from a list of rooms (with a basic/comfort preset per slot) assemble a new, validated project → an allocation manifest + ETS GA XML/CSV + a device BOM proposal. Dry-run, new projects only (R1).

Under the hood: a device library that expands each actuator into its real communication objects — from generic recipes up to the exact vendor object model parsed straight from ETS application programs.

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

🎬 Explore the live interactive demo & dashboard →

New — a whole demo house. examples/demo-home ships a synthetic 239-GA / 47-Function project, the tool's generated report + Home Assistant config + ETS export, and a full smart-home “brain” — circadian lighting, an 8-factor climate setpoint, a presence/season/time state machine and statistics — driving a 5-view dashboard. See it all on the live site ↗.

🖥️ The dashboard — live in Home Assistant

Real screenshots from a live Home Assistant running the demo house. They show the tool's assembled entities at work: RGBW / RGB / CCT colour lights, six floor-heating climate zones (target, mode and valve %), a circadian lighting curve and a computed climate setpoint — not set by hand.

Climate	Lighting
Energy & stats	Presence

▶ Explore it interactively on the live site → · config in examples/demo-home/ha-brain

🧪 Status & call for testers

This is a public beta. The full pipeline passes an end-to-end smoke test on a synthetic project and has been validated against real multi-thousand-GA ETS5/ETS6 projects (anonymised) — but real ETS projects are wonderfully messy and diverse, and more field reports make it better.

👉 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.

💬 Join the discussion → — say hi, ask anything, or share what the tool found on your project.

🗺️ Roadmap — shaped by real integrators

Recent reviews from practising KNX integrators (in Discussions) are steering what comes next:

• Cross-device parameter consistency (shipped — check_device_parameters) — flag the one device whose ETS parameter settings differ from its N identical siblings: a thermostat with a different setpoint/hysteresis, a presence detector with a different detection time. Extracts per-device parameters straight from the .knxproj and finds the odd one out on real 42–275-device projects — read-only, no ETS, no bus — and correctly reports nothing on a clean project (no false positives across a different vendor / integrator school).
• Project Policy Profile (shipped — check_policy) — validate a project against your own agreed rules (naming, GA taxonomy, command/status exemptions) instead of one universal "professional standard", since conventions differ per integrator; with no profile it validates against the taxonomy inferred from the project itself.
• Room Template Library — compose a new project from parametrised room templates. R1 shipped (compose_rooms + validate_room_template: new projects, dry-run, allocation manifest + ETS XML/CSV + device BOM). R2 planned: docking into an existing project + exact device selection.
• On in-ETS group-address linking we deliberately don't reinvent the wheel: for linking GAs to communication objects inside ETS there are already ETS App-Store add-ins today, and native Smart Linking is coming in ETS7 — we point you to those and keep our focus on read-only audit and an evidential project model.

Have a project to test, a workflow that breaks, or a feature to shape? → Discussions.

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 you can do with it

📐 Scenario 1 — Design a project from a spec (spec → implementation kit)

Turn a project specification (equipment schedules, cable journals, a device list) into a complete, validated group-address structure — and the full document set to implement it:

1. Device list → object model. Each device expands into its real communication objects via the device library (decompose_device): a dimmer channel is on/off + status + relative dim (3.007) + absolute value (5.001) + brightness status — not "one GA"; a floor-heating zone is 8 objects; a pulse meter is 6.
2. The professional logic layer. A bare spec never mentions what makes a project complete: central & zone macros, scenes, presence logic, climate-control scaffolding, sun/wind shutter logic, leak→shut-off chains, astro/meteo and date-time sources, reserves in every range. The methodology encodes these completeness patterns — distilled from the KNX Association standard, public manufacturer documentation and the study of real professional as-built ETS projects (anonymised).
3. Structure & discipline. 3-level addressing, zone+function naming, command↔status pairing, a DPT on every address.
4. Deliverables (one command each): ETS-importable XML/CSV · Markdown report · Home Assistant YAML · functional acceptance test protocol · as-built handover pack (inventory, GA map, coverage %, Secure posture, QA findings, topology SVG).

Full methodology: docs/spec-to-structure.md. Field-checked by reconstructing a real as-built ETS project (3,600+ group addresses) from its specification alone: ~92 % structural match (taxonomy, domains, automation logic, DPT distribution) at zero validation errors — the remaining delta is the integrator's per-device parameterisation, which no spec encodes.

🔍 Scenario 2 — Audit, repair & finish an existing project

• Read & classify. Parses password-protected ETS5/ETS6 .knxproj via xknxproject; classifies every GA by category (lighting / shutter / hvac / sensor / scene / energy / diagnostics) and kind (command / status / sensor) from the DPT + multilingual (EN/DE/RU) name keywords. GA purpose tagging (functional / reserve / logic / scratch) keeps intentional placeholders out of the error lists, so the report doesn't cry wolf (on a real 685-GA project: false errors 29 → 6).
• Validate (analyze_all runs everything): naming & structure · missing status objects (ETS-Function roles first, then name-token pairing, positional pairing — parallel status middles with 1:1 names — and self-reporting R+T objects) · missing/inconsistent DPTs + sub-DPT sanity (a "temperature" GA carrying 5.001 gets flagged) · relative-only dimmers · KNX Secure posture (secured vs plaintext, mixed groups, keyring checklist — key material is never read) · Matter-readiness · energy-domain coverage.
• Repair, not just flag (suggest_repairs): infer a DPT from the name, correct a suspect sub-DPT, synthesise a missing status GA in a free address slot, add an absolute-brightness GA. Suggestions only — a human reviews, accepted GAs feed the ETS export. On a real 3,646-GA project: 145 concrete proposals (32 DPT inferences, 112 synthesised status GAs).
• Finish the job: grade_completeness (bare skeleton → as-built score), suggest_names, diff_projects (semantic diff of two .knxproj revisions: added / removed / DPT-changed / renamed / secure-changed), then regenerate the report, handover pack and test protocol.

🏠 Scenario 3 — Generate the smart-home layer (Home Assistant)

• Assembled entities, conservatively: covers → colour / dimmable lights (on/off + brightness + RGBW/RGB/colour-temperature + statuses) → switches → climate (current temp, target-temp status, operation/controller mode, valve value) → sensors/binary. Every entity gets a state_address wherever the device can report — HA reads real state, never assumes.
• Review-first: anything ambiguous (DPT 5.001 — brightness or blind position?) is not guessed — it goes to a review list with an explanation (including actuator-dependent cover flags like invert_position / travel times, which no .knxproj encodes).
• Extras: expose block for date/time broadcast (DPT 19.001), Matter-readiness lint, KNX IoT (Turtle/RDF) semantic export.
• Live control of the house stays in the official Home Assistant integration (layer 1) — this server only prepares its configuration.
• Ops companion: skills/ha-git-backup — the life of your config after deploy: a real git history of /config (deploy key + pre-commit secret scanner) plus encrypted offsite backups in GitHub Releases, with a monthly restore drill.

🧱 Scenario 4 — Compose a new project from room templates

• From rooms, not a blank sheet: pick from six built-in parametrised room templates (bedroom, children, living, kitchen, bathroom, corridor), choose a basic / comfort preset per slot (a house can mix comfort climate with basic lighting), and compose_rooms assembles a new project.
• Out comes: an allocation manifest (main = domain, middle = role, sub sequential), ETS-importable GA XML/CSV via the existing generators, and a device BOM proposal from the device library.
• Validated by the real reader: the generated .knxproj is re-read through the standard load_project — the same path used for third-party projects — and passes all four linters (naming / missing-status / DPT / policy) with 0 errors / 0 warnings.
• Dry-run by default, new projects only. The template format is a public contract (room_templates/SCHEMA.md): identity is a locale-neutral slot_id, never a human name.
• _{R2: docking into an existing project + exact device selection — planned.}

🧩 The foundation — a growing device library

• parse_devices_from_project extracts exact vendor object models — including ref-level (ComObjectRef) publishers like HDL/Ekinex — from the manufacturer application programs inside any .knxproj / .knxprod: object numbers, names, sizes, DPTs, C/R/W/T/U flags, per-channel block strides — deterministically, and PII-safe (vendor catalog data only; the client project part of the file is never read).
• Point NICKOL_KNX_CATALOG at your catalog and decompose_device answers with the exact model (catalog-exact) instead of a generic recipe — the catalog grows on demand, from the projects and product databases you feed it.
• Objects the vendor ships without a declared DPT stay honestly unverified — never guessed.

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 (31)

Read

Validate

Repair & design

Generate

Room Library (R1 — compose a new project from room templates)

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.
• Validated on a synthetic demo project and on real multi-thousand-GA ETS5/ETS6 projects (anonymised) — but real .knxproj files vary enormously, and it is still a beta. 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.
• Hardened against hostile project files. A .knxproj is an untrusted ZIP-of-XML, so parsing runs through safexml.py: DTD/entity XML is refused (billion-laughs / XXE), and archives are pre-flighted against size / entry / decompression-ratio caps with path-traversal names rejected (zip-bomb defense).
• 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)
│   ├── safexml.py        # hardened ZIP/XML parsing of untrusted .knxproj (zip-bomb / XXE defense)
│   ├── 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
│   ├── room_library.py   # Room Library R1 — compose a new project from templates
│   ├── room_templates/   # built-in room YAML templates + SCHEMA.md (public contract)
│   └── server.py         # FastMCP server, 31 tools, confined writes
├── tests/test_pipeline.py
├── examples/claude_desktop_config.json
├── skills/
│   └── ha-git-backup/    # ops companion: 2-circuit HA backup (git history + encrypted offsite)
├── 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.