nickol-knx-mcp

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

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

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.

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.

🧩 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 (25)

Read

Validate

Repair & design

Generate

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.
• 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, 25 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.