nickol-knx-mcp

Ein KNX / ETS6-Design-Assistent, bereitgestellt als MCP-Server.

Vier Dinge, die Sie damit tun können – ohne jemals den live-KNX-Bus zu berühren:

1. Ein Projekt aus einer Spezifikation entwerfen – eine Geräteliste / Projektspezifikation in eine vollständige, validierte Gruppenadressenstruktur plus den vollständigen Implementierungs-Dokumentensatz umwandeln (ETS-importierbares XML/CSV, menschenlesbarer Bericht, Home Assistant YAML, Abnahmeprüfprotokoll, As-Built-Übergabepaket).

2. Ein bestehendes Projekt prüfen, reparieren & fertigstellen – Namensgebung · DPT & Sub-DPT · Befehl↔Status · KNX Secure · Matter-Readyness validieren, konkrete Korrekturvorschläge erhalten (abgeleitete DPTs, synthetisierte Status-GAs), Vollständigkeit bewerten und zwei Projektversionen vergleichen.

3. Die Smart-Home-Ebene generieren – zusammengestellte Home Assistant Entitäten (Farblicht, Klima, Beschattung, Sensoren), die tatsächlichen Gerätezustand auslesen, wobei alles Mehrdeutige zur manuellen Prüfung zurückgestellt wird.

4. Ein neues Projekt aus parametrisierten Raumvorlagen zusammenstellen – aus einer Liste von Räumen (mit einem basic/comfort-Preset pro Slot) ein neues, validiertes Projekt zusammenstellen → ein Zuordnungsmanifest + ETS GA XML/CSV + einen Geräte-BOM-Vorschlag. Trockenlauf, nur neue Projekte (R1).

Im Hintergrund: eine Gerätebibliothek, die jeden Aktor in seine realen Kommunikationsobjekte aufschlüsselt – von generischen Rezepten bis zum exakten Hersteller-Objektmodell, das direkt aus ETS-Anwendungsprogrammen geparst wird.

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

Neu – ein komplettes Demo-Haus. examples/demo-home enthält ein synthetisches 239-GA / 47-Funktionen-Projekt, den generierten Bericht des Tools + Home Assistant Konfiguration + ETS Export sowie ein vollständiges Smart-Home „Gehirn“ – zirkadiane Beleuchtung, einen 8-Faktor-Klima-Sollwert, eine Anwesenheits-/Jahreszeit-/Tageszeit-Zustandsmaschine und Statistiken – das ein 5-Ansichten-Dashboard antreibt. Sehen Sie alles auf der Live-Seite ↗.

🖥️ Das Dashboard – live in Home Assistant

Echte Screenshots eines laufenden Home Assistant, der das Demo-Haus ausführt. Sie zeigen die vom Tool zusammengestellten Entitäten in Aktion: RGBW / RGB / CCT Farblicht, sechs Fußbodenheizungs-Klimazonen (Sollwert, Modus und Ventil %), eine zirkadiane Beleuchtungskurve und einen berechneten Klima-Sollwert – nicht von Hand gesetzt.

▶ Erkunden Sie es interaktiv auf der Live-Seite → · Konfiguration in examples/demo-home/ha-brain

Related MCP server: mcp-codebase-oracle

🧪 Status & Aufruf für Tester

Dies ist eine öffentliche Beta. Die gesamte Pipeline besteht einen End-to-End-Smoke-Test an einem synthetischen Projekt und wurde gegen echte Multi-Tausend-GA-ETS5/ETS6-Projekte (anonymisiert) validiert – aber echte ETS-Projekte sind wunderbar chaotisch und vielfältig, und mehr Feldberichte machen es besser.

👉 Wenn Sie ein ETS5/ETS6-Projekt haben, probieren Sie es bitte aus und teilen Sie uns mit, was passiert. Eröffnen Sie ein Realprojekt-Testbericht-Issue. Das Tool ist schreibgeschützt und verbindet sich nie mit einem Bus, daher ist das Testen sicher (siehe Sicherheitsmodell). Einzelheiten finden Sie in CONTRIBUTING.md.

💬 Nehmen Sie an der Diskussion teil → – sagen Sie Hallo, fragen Sie alles oder teilen Sie mit, was das Tool in Ihrem Projekt gefunden hat.

🗺️ Roadmap – geformt von echten Integratoren

Aktuelle Rückmeldungen von praktizierenden KNX-Integratoren (in Discussions) lenken, was als Nächstes kommt:

• Geräteübergreifende Parameterkonsistenz (ausgeliefert – check_device_parameters) – das eine Gerät markieren, dessen ETS Parameter-Einstellungen von seinen N identischen Geschwistern abweichen: ein Thermostat mit einem anderen Sollwert/Hysterese, ein Präsenzmelder mit einer anderen Erfassungszeit. Extrahiert gerätespezifische Parameter direkt aus der .knxproj und findet den Ausreißer bei echten 42–275-Geräte-Projekten – schreibgeschützt, kein ETS, kein Bus – und meldet korrekt nichts bei einem sauberen Projekt (keine Fehlalarme über verschiedene Hersteller / Integratorenschulen hinweg).

• Projekt-Policy-Profil (ausgeliefert – check_policy) – ein Projekt gegen Ihre eigenen vereinbarten Regeln validieren (Namensgebung, GA-Taxonomie, Befehl/Status-Ausnahmen) anstelle eines universellen "Professionellen Standards", da Konventionen je nach Integrator variieren; ohne Profil wird anhand der aus dem Projekt selbst abgeleiteten Taxonomie validiert.

• Raumvorlagen-Bibliothek – ein neues Projekt aus parametrisierten Raumvorlagen zusammenstellen. R1 ausgeliefert (compose_rooms + validate_room_template: neue Projekte, Trockenlauf, Zuordnungsmanifest + ETS XML/CSV + Geräte-BOM). R2 geplant: Andocken an ein bestehendes Projekt + exakte Geräteauswahl.

• Logic Machine Support (kommt – in der Recherche) – dasselbe schreibgeschützte Entwurfszeitmodell auf Logic Machine (Embedded Systems) Installationen übertragen: ein LM-basiertes KNX-Projekt parsen und dieselben Namens-/DPT-/Status-/Topologie-Audits durchführen sowie dieselbe Übergabeausgabe erzeugen, damit LM-Integratoren dasselbe nachweisliche Projektmodell erhalten, das sie bereits von einer rohen .knxproj bekommen. Derzeit wird der Umfang anhand eines realen Logic Machine 5 Geräts abgesteckt.

• Bei der ETS-internen Gruppenadressverknüpfung erfinden wir bewusst nicht das Rad neu: Für die Verknüpfung von GAs mit Kommunikationsobjekten innerhalb von ETS gibt es heute bereits ETS App-Store-Add-Ins, und natives Smart Linking kommt in ETS7 – wir verweisen Sie darauf und konzentrieren uns auf schreibgeschützte Prüfung und ein nachweisliches Projektmodell.

Haben Sie ein Projekt zum Testen, einen Workflow, der kaputt geht, oder eine Funktion, die Sie gestalten möchten? → Discussions.

Warum es dies gibt

Stand Mitte 2026 gibt es kein fertiges ETS6 ↔ Claude / MCP-Tool. Die KNX-Community hat explizit nach einer Integration gefragt, die Projekte inspizieren und bei der Änderung unterstützen kann (Geräte und Gruppenadressen hinzufügen/umbenennen) durch einen AI/CLI-Workflow. Dieses Paket füllt genau die Entwurfszeit-Schicht – die fehlende.

Der empfohlene vollständige Aufbau besteht aus vier Schichten; nur eine muss von Grund auf neu gebaut werden:

Sicherheit durch Design: Schicht 2 (dieser Server) kann physikalisch nicht mit einem Bus verbinden. Es hat keine Netzwerk-/Bus-Abhängigkeit – es liest nur .knxproj und schreibt Dateien in einen eingeschränkten Arbeitsbereich. Die Anforderung "niemals auf einen Live-Bus schreiben" wird strukturell durchgesetzt, nicht durch Versprechen. Jede tatsächliche Interaktion mit dem Haus erfolgt nur über Schicht 1 (Home Assistant).

Was Sie damit tun können

📐 Szenario 1 – Ein Projekt aus einer Spezifikation entwerfen (Spezifikation → Implementierungsset)

Verwandeln Sie eine Projektspezifikation (Gerätepläne, Kabeljournale, eine Geräteliste) in eine vollständige, validierte Gruppenadressenstruktur – und das vollständige Dokumentenset zur Implementierung:

1. Geräteliste → Objektmodell. Jedes Gerät wird mithilfe der Gerätebibliothek (decompose_device) in seine tatsächlichen Kommunikationsobjekte expandiert: Ein Dimmerkanal besteht aus Ein/Aus + Status + relativer Dimmung (3.007) + Absolutwert (5.001) + Helligkeitsstatus – nicht „eine GA“; eine Fußbodenheizzone besteht aus 8 Objekten; ein Impulszähler aus 6.

2. Die professionelle Logikschicht. Eine reine Spezifikation erwähnt nie, was ein Projekt vollständig macht: zentrale & Zonenmakros, Szenen, Präsenzlogik, Klimasteuerungs-Gerüst, Sonnen-/Wind-Jalousiesteuerung, Leckage→Absperrketten, Astro-/Meteo- und Datums-/Zeitquellen, Reserven in jedem Bereich. Die Methodik kodiert diese Vollständigkeitsmuster – destilliert aus dem KNX Association-Standard, öffentlicher Herstellerdokumentation und der Untersuchung realer professioneller ETS-Projekte im Ist-Zustand (anonymisiert).

3. Struktur & Disziplin. 3-stufige Adressierung, Zonen+Funktions-Benennung, Befehl↔Status-Paarung, ein DPT auf jeder Adresse.

4. Liefergegenstände (jeweils ein Befehl): In ETS importierbares XML/CSV · Markdown-Bericht · Home Assistant YAML · funktionales Abnahmeprüfprotokoll · Übergabepaket im Ist-Zustand (Inventar, GA-Plan, Abdeckungsgrad %, Secure-Posture, QA-Fundstücke, Topologie-SVG).

Vollständige Methodik: docs/spec-to-structure.md. Feldgeprüft durch Rekonstruktion eines realen ETS-Projekts im Ist-Zustand (3.600+ Gruppenadressen) allein anhand seiner Spezifikation: ~92 % strukturelle Übereinstimmung (Taxonomie, Domänen, Automatisierungslogik, DPT-Verteilung) bei null Validierungsfehlern – das verbleibende Delta ist die gerätespezifische Parametrierung des Integrators, die keine Spezifikation abbildet.

🔍 Szenario 2 – Vorhandenes Projekt prüfen, reparieren & fertigstellen

• Einlesen & Klassifizieren. Analysiert passwortgeschützte ETS5/ETS6 .knxproj-Dateien über xknxproject; klassifiziert jede GA nach Kategorie (Licht / Rollladen / HLK / Sensor / Szene / Energie / Diagnose) und Art (Befehl / Status / Sensor) anhand des DPTs + mehrsprachiger (EN/DE/RU) Namensschlüsselwörter. GA Zweck-Tagging (functional / reserve / logic / scratch) hält absichtliche Platzhalter aus den Fehlerlisten heraus, sodass der Bericht keinen falschen Alarm gibt (bei einem realen 685-GA-Projekt: falsche Fehler 29 → 6).

• Validieren (analyze_all führt alles aus): Benennung & Struktur · fehlende Statusobjekte (zuerst ETS-Funktionsrollen, dann Namens-Token-Paarung, positionelle Paarung – parallele Status-Mittelfelder mit 1:1-Namen – und selbstmeldende R+T-Objekte) · fehlende/inkonsistente DPTs + Sub-DPT-Plausibilität (eine „Temperatur“-GA mit 5.001 wird gemeldet) · reine-Dimmer-Relativwerte · KNX-Secure-Posture (gesichert vs. Klartext, gemischte Gruppen, Keyring-Checkliste – Schlüsselmaterial wird nie gelesen) · Matter-Readyness · Energiebereichsabdeckung.

• Reparieren, nicht nur melden (suggest_repairs): einen DPT aus dem Namen ableiten, einen verdächtigen Sub-DPT korrigieren, eine fehlende Status-GA in einem freien Adressplatz synthetisieren, eine Absoluthelligkeits-GA hinzufügen. Nur Vorschläge – ein Mensch prüft, akzeptierte GAs fließen in den ETS-Export ein. Bei einem realen 3.646-GA-Projekt: 145 konkrete Vorschläge (32 DPT-Ableitungen, 112 synthetisierte Status-GAs).

• Den Job zu Ende bringen: grade_completeness (rohes Skelett → Ist-Zustand-Score), suggest_names, diff_projects (semantischer Vergleich zweier .knxproj-Revisionen: hinzugefügt / entfernt / DPT-geändert / umbenannt / secure-geändert), dann Bericht, Übergabepaket und Testprotokoll neu generieren.

🏠 Szenario 3 – Smart-Home-Schicht generieren (Home Assistant)

• Entitäten konservativ zusammengebaut: Abdeckungen → Farb-/Dimmbare Leuchten (Ein/Aus + Helligkeit + RGBW/RGB/Farbtemperatur + Status) → Schalter → Klima (aktuelle Temperatur, Solltemperatur-Status, Betriebs-/Reglermodus, Ventilwert) → Sensoren/Binäreingänge. Jede Entität erhält eine state_address, wo immer das Gerät melden kann – HA liest echten Zustand, niemals Annahmen.

• Prüfung zuerst: Alles, was mehrdeutig ist (DPT 5.001 – Helligkeit oder Jalousieposition?), wird nicht geraten – es geht in eine review-Liste mit einer Erklärung (einschließlich aktorabhängiger Abdeckungsflags wie invert_position / Fahrzeiten, die keine .knxproj kodiert).

• Extras: expose-Block für Datum/Zeit-Broadcast (DPT 19.001), Matter-Readyness-Lint, KNX-IoT (Turtle/RDF)-semantischer Export.

• Die Live-Steuerung des Hauses bleibt in der offiziellen Home-Assistant-Integration (Schicht 1) – dieser Server bereitet nur dessen Konfiguration vor.

• Betriebsbegleiter: skills/ha-git-backup – das Leben Ihrer Konfiguration nach dem Deployment: eine echte Git-Historie von /config (Deploy-Key + Pre-Commit-Secret-Scanner) plus verschlüsselte Offsite-Backups in GitHub Releases, mit monatlichem Wiederherstellungsübung.

🧱 Szenario 4 – Neues Projekt aus Raumvorlagen zusammenstellen

• Von Räumen, nicht von einem leeren Blatt: Wählen Sie aus sechs eingebauten parametrisierten Raumvorlagen (Schlafzimmer, Kinder-, Wohnzimmer, Küche, Badezimmer, Flur), wählen Sie ein basic-/comfort-Preset pro Steckplatz (ein Haus kann Komfort-Klima mit Basic-Beleuchtung mischen), und compose_rooms setzt ein neues Projekt zusammen.

• Heraus kommt: ein Allokations-manifest (Haupt = Domäne, Mittel = Rolle, Sub sequentiell), in ETS importierbares GA-XML/CSV über die vorhandenen Generatoren und ein Geräte-Stücklistenvorschlag aus der Gerätebibliothek.

• Validierung durch den echten Reader: Das generierte .knxproj wird über den Standard load_project erneut eingelesen – denselben Pfad, der auch für Drittanbieter-Projekte verwendet wird – und besteht alle vier Linter (Benennung / fehlender Status / DPT / Policy) mit 0 Fehlern / 0 Warnungen.

• Standardmäßig Trockenlauf, nur neue Projekte. Das Vorlagenformat ist ein öffentlicher Vertrag (room_templates/SCHEMA.md): Identität ist eine locale-neutrale slot_id, niemals ein menschlicher Name.

• R2: Andocken an ein bestehendes Projekt + exakte Geräteauswahl – geplant.

🧩 Das Fundament – eine wachsende Gerätebibliothek

• parse_devices_from_project extrahiert exakte Hersteller-Objektmodelle – einschließlich Ref-Level (ComObjectRef)-Publisher wie HDL/Ekinex – aus den Hersteller-Anwendungsprogrammen in jedem .knxproj / .knxprod: Objektnummern, Namen, Größen, DPTs, C/R/W/T/U-Flags, blockweise Kanal-Offsets – deterministisch und PII-sicher (nur Herstellerkatalogdaten; der Client-Projektteil der Datei wird nie gelesen).

• Setzen Sie NICKOL_KNX_CATALOG auf Ihren Katalog, und decompose_device antwortet mit dem exakten Modell (catalog-exact) statt mit einem generischen Rezept – der Katalog wächst on demand aus den Projekten und Produktdatenbanken, die Sie ihm füttern.

• Objekte, die der Hersteller ohne deklarierten DPT ausliefert, bleiben ehrlich unverified – nie geraten.

Alle Schreibvorgänge gehen nur in das Workspace-Verzeichnis (NICKOL_KNX_WORKSPACE, Standard ./knx-workspace); Schreibvorgänge außerhalb werden abgelehnt.

Installation

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

Abhängigkeiten: mcp>=1.10, xknxproject>=3.8, PyYAML>=6.0.

Unter Debian/Ubuntu, wenn pip sich über eine extern verwaltete Umgebung beschwert, verwenden Sie eine venv (wie oben) oder pip install -e . --break-system-packages. Falls PyJWT Konflikte verursacht, führen Sie zuerst pip install mcp --ignore-installed PyJWT aus.

Überprüfen:

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

Verbindung mit Claude herstellen

Claude Desktop

examples/claude_desktop_config.json verbindet nickol-knx + filesystem + git + home-assistant. Minimaler Ausschnitt (macOS-Konfigurationspfad: ~/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

Legen Sie dann CLAUDE.md in Ihrem Projektstamm ab – es fungiert als ETS-Assistent-Skill (Entwurfsregeln, Sicherheitsregeln, 3-stufige GA-Struktur, Befehl/Status-Paarung, DPT-Disziplin, Benennung, KNX-Secure-Keyring-Handhabung und der empfohlene Workflow).

MCP-Tools (31)

Lesen

Reparatur & Entwurf

Generieren

Raumbibliothek (R1 — ein neues Projekt aus Raumvorlagen zusammenstellen)

Typischer Arbeitsablauf

1. load_project → auf Ihre .knxproj verweisen (+ Passwort, falls geschützt).

2. analyze_all oder project_report → Ergebnisse lesen; zuerst menschlich prüfen.

3. Namensgebung/DPT/Status in ETS korrigieren (durch Import generierter GAs oder manuell).

4. generate_ets_group_addresses(fmt="xml") → die fehlenden GAs in ETS importieren.

5. generate_ha_package → das YAML in Home Assistant einfügen; review‑Einträge manuell abarbeiten.

6. Alles (.knxproj‑Export, HA‑Konfigurationen, Adressschema) in Git versionieren.

7. Das Live‑Haus nur über das Home‑Assistant‑MCP (Ebene 1) berühren.

Einschränkungen (ehrlich)

• Die Klassifizierung von Befehl/Status und Kategorie ist eine Heuristik (DPT + Namen + ETS‑Funktionen). Bei unübersichtlichen Projekten ohne Funktionen und mit nicht standardgemäßen Namen sind Fehlalarme möglich — deshalb ist der Bericht immer für die menschliche Prüfung gedacht, und Unklarheiten landen in review, nicht in der Konfiguration.

• DPT 5.001 ist strukturell mehrdeutig (Helligkeit vs. Position); die Unterscheidung erfolgt über Schlüsselwörter — bei nicht standardgemäßen Namen bitte gegenprüfen.

• Der HA‑Generator ist konservativ: Er schiebt ein Element lieber in review, als eine falsche Entität auszugeben.

• Der Server schreibt nie auf den Bus und kommuniziert nie direkt mit ETS — der ETS‑Austausch erfolgt ausschließlich über Datei‑Import/Export von GAs.

• Validierung an einem synthetischen Demoprojekt und an realen Projekten mit mehreren tausend GAs (ETS5/ETS6) (anonymisiert) — aber echte .knxproj‑Dateien variieren enorm, und es ist immer noch eine Beta. Daher der Aufruf an Tester.

🔒 Sicherheitsmodell

• Strukturell kein Buszugriff. Es gibt keine Netzwerk‑ oder Busbibliothek im Abhängigkeitsbaum. workspace_info() meldet bus_access: false.

• Nur Lesezugriff auf Ihr Projekt. project.py ist das einzige Modul, das .knxproj berührt, und es liest nur.

• Begrenzte Schreibvorgänge. Die gesamte Ausgabe ist auf NICKOL_KNX_WORKSPACE beschränkt; Pfade außerhalb werden abgelehnt.

• Gegen feindliche Projektdateien gehärtet. Eine .knxproj ist ein unsicheres ZIP‑von‑XML, daher erfolgt das Parsen über safexml.py: DTD‑/Entity‑XML wird abgelehnt (Billion‑Laughs / XXE), und Archive werden vorab auf Größen‑/Eintrags‑/Dekompressionsverhältnis‑Grenzen geprüft, wobei Pfad‑Traversal‑Namen abgelehnt werden (Zip‑Bomb‑Abwehr).

• Mensch im Kreislauf. Erstellen Sie einen project_report und prüfen Sie ihn bevor Sie ihn in ETS importieren oder in Home Assistant ausrollen.

Sicherheitsproblem gefunden? Siehe SECURITY.md.

Paketstruktur

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

Mitwirken

Tester und Mitwirkende sind sehr willkommen — insbesondere Testberichte von realen Projekten. Siehe CONTRIBUTING.md und die Issue‑Vorlagen.

Lizenz

MIT © 2026 Nikolay Miroshnichenko

Nicht verbunden mit oder unterstützt durch die KNX Association. „KNX“ und „ETS“ sind Marken der KNX Association cc. Dies ist ein unabhängiges Community‑Tool.