Developer MCP Tool for OpenWebNet Protocol Validation, WHO Specifications, and Home Assistant Integration Knowledge. Deterministic syntax checking, formal WHO catalog reference, and AST signature introspection for AI coding assistants.
openwebnet-mcp is an offline, read-only Model Context Protocol (MCP) server built with Python 3.11+ using the FastMCP framework. It provides AI coding assistants (Claude Desktop, Cursor, VS Code, Antigravity) with fast semantic lookups, deterministic frame grammar validation, and reference documentation for OpenWebNet WHO families and Home Assistant myhome configuration patterns.
{
"mcpServers": {
"openwebnet-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/OpenWebNet-HA/openwebnet-mcp.git", "openwebnet-mcp"]
}
}
}{
"mcpServers": {
"openwebnet-mcp": {
"command": "python",
"args": ["-m", "openwebnet_mcp.server"],
"cwd": "/path/to/openwebnet-mcp"
}
}
}Once connected, your AI coding assistant can browse documentation, interpret frames, and generate verified code autonomously.
User Prompt:
"I saw this frame on my SCS bus trace:
*#4*1*#14*0215*1##. What does it mean and which hardware is involved?"
AI Agent Action:
- Calls
parse_and_validate_frame("*#4*1*#14*0215*1##"). - Resolves WHO=4 (Heating/Thermoregulation), Dimension 14 (Target Temperature & Mode), Zone 1, Target 21.5°C, Mode 1 (Heating).
- Returns human-readable breakdown and lists compatible thermostat units (3550, L4691).
User Prompt:
"How do I configure my BTicino 3477 CEN+ interface to toggle a light when button 2 is pressed, and what OpenWebNet frames are sent?"
AI Agent Action:
- Calls
get_ha_guide("cen_scenarios")to review the CEN vs CEN+ specifications and Home Assistant blueprint. - Calls
draft_own_frame(who=25, command_type="command", where="11", what="21#2")to show the short-press pulse frame*25*21#2*11##. - Calls
draft_ha_config(platform="light", ...)to draft the complete automation YAML.
User Prompt:
"My dimmable lights jump instantly to brightness instead of ramping smoothly when I pass
transition: 5. Why?"
AI Agent Action:
- Calls
search_documentation("transition stepped dimming"). - Reads the technical design document explaining hardware ramp limitations in older F411/F418 actuators vs software-emulated stepped dimming.
- Suggests the proper configuration and command sequence.
| Tool | Description |
|---|---|
search_documentation |
Ranked keyword and fuzzy search across all protocol specs, guides, and design docs. |
get_who_spec |
Retrieve full technical specification, WHAT commands, and DIMENSIONS for a WHO family. |
list_who_catalog |
Summary inventory table of all 20+ OpenWebNet WHO families with archive status. |
get_ha_guide |
Full markdown guide for configuring and troubleshooting Home Assistant MyHOME platforms. |
lookup_frame_syntax |
Grammar, regex templates, and parameter formats for OpenWebNet message types. |
parse_and_validate_frame |
Deep syntax and semantic validation of any raw OpenWebNet frame string. |
draft_own_frame |
Construct and validate a syntactically correct OpenWebNet frame string. |
draft_ha_config |
Generate production-ready Home Assistant configuration YAML for MyHOME entities. |
get_code_signature |
Inspect Python AST signatures and docstrings from custom_components/myhome or OWNd. |
rescan_documentation |
Flush caches and reload all OpenWebNet specifications, documents, and AST models. |
| URI | Description |
|---|---|
spec://who-catalog |
Read-only catalog of all OpenWebNet WHO families. |
spec://protocol-grammar |
Read-only formal OpenWebNet grammar, regex patterns, and session specs. |
docs://toc |
Master Table of Contents for all indexed OpenWebNet & MyHOME documentation. |
docs://guide/{topic} |
Read-only full text of a specific documentation guide. |
| Prompt / Slash Command | Description |
|---|---|
/boost [topic] |
Injects authoritative OpenWebNet protocol architecture, WHO subsystem mappings, frame delimiters, and modern Home Assistant /config/myhome.yaml standards directly into the AI agent context window. |
In Claude Desktop, Cursor, or Antigravity, trigger the prompt by typing /boost or selecting it from the prompt menu:
/boost topic: lighting
The server primes the LLM with strict frame grammar rules, hardware capabilities, and modern Home Assistant configuration standards, eliminating hallucinated syntax.
| WHO | Subsystem | Official Title | Status | HA Platform |
|---|---|---|---|---|
| 0 | Scenarios (Basic) | WHO_0.pdf |
🟢 Archived | event |
| 1 | Lighting | WHO_1.pdf |
🟢 Archived | light |
| 2 | Automation (Covers) | WHO_2.pdf |
🟢 Archived | cover |
| 3 | Load Control | WHO_3.pdf |
🟡 Legacy | switch, sensor |
| 4 | Thermoregulation | WHO_4 2.pdf |
🟢 Archived | climate, sensor |
| 5 | Burglar Alarm | WHO_5.pdf |
🟢 Archived | alarm_control_panel |
| 6 | Door Entry Call & Lock | WHO_6.pdf |
🟡 Legacy | lock, event |
| 7 | Video Door Entry | WHO_7.pdf |
🟢 Archived | camera |
| 9 | Auxiliary | WHO_9.pdf |
🟡 Legacy | switch |
| 13 | Gateway Management | WHO_13.pdf |
🟢 Archived | Diagnostics |
| 14 | Actuators & Lock | (Reverse-Engineered) | 🟢 Documented | Diagnostics, lock |
| 15 | CEN Pushbuttons | WHO_15.pdf |
🟢 Archived | event |
| 16 | Sound System | WHO_16.pdf |
🟢 Archived | media_player |
| 17 | MH200N Scenarios | WHO_17.pdf |
🟢 Archived | event |
| 18 | Energy Management | WHO_18.pdf |
🟢 Archived | sensor |
| 22 | Sound Diffusion (Ext) | WHO_22.pdf |
🟢 Archived | media_player |
| 24 | Lighting / DALI | WHO_24.pdf |
🟢 Archived | light |
| 25 | CEN+ / Dry Contacts | WHO_25.pdf |
🟢 Archived | event, binary_sensor |
| 1001 | Bus Diagnostics | WHO_1001.pdf |
🟢 Archived | Diagnostics |
| 1004 | Heating Diagnostics | WHO_1004.pdf |
🟢 Archived | Diagnostics |
| 1013 | Gateway Diagnostics | WHO_1013.pdf |
🟢 Archived | Diagnostics |
Run unit tests and verify coverage with pytest:
pip install -e ".[dev]"
pytest --cov=src/openwebnet_mcp --cov-report=term-missingMIT License. Copyright (c) 2026 OpenWebNet-HA Community.