openwebnet-mcp
An offline, read-only MCP server that gives AI coding assistants authoritative OpenWebNet protocol knowledge, deterministic frame validation, and Home Assistant MyHOME configuration guidance.
Search indexed OpenWebNet specs, guides, and design docs (
search_documentation)Look up full WHO family specs, WHAT commands, and DIMENSIONs (
get_who_spec,list_who_catalog)Read complete Home Assistant MyHOME platform guides and troubleshooting docs (
get_ha_guide)Look up message grammar, regex templates, and parameter formats (
lookup_frame_syntax)Parse and semantically validate raw OpenWebNet frames, enriched with firmware-oracle evidence (
parse_and_validate_frame)Draft and validate syntactically correct OpenWebNet frames (
draft_own_frame)Generate production-ready Home Assistant YAML for lights, covers, climate, sensors, binary sensors, switches, and media players (
draft_ha_config)Inspect Python AST signatures and docstrings from
custom_components/myhomeorOWNd(get_code_signature)Flush caches and reload specs, documents, AST models, Machine KB, and firmware verdicts (
rescan_documentation)
Note: the README advertises 15 tools plus resources and a /boost prompt, but this schema exposes 11 tools (the Machine KB and firmware-oracle lookup tools are absent here).
Provides tools for configuring and troubleshooting Home Assistant MyHOME platforms, including generating Home Assistant configuration YAML for MyHOME entities and automations controlled via OpenWebNet devices.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openwebnet-mcp Decode this OpenWebNet frame: *#1*2*15##"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OpenWebNet-MCP Server
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.
🚀 Quick Start
1. Add to your MCP Client Configuration
Claude Desktop / Cursor / VS Code (mcp.json):
{
"mcpServers": {
"openwebnet-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/OpenWebNet-HA/openwebnet-mcp.git", "openwebnet-mcp"]
}
}
}Local Development Run:
{
"mcpServers": {
"openwebnet-mcp": {
"command": "python",
"args": ["-m", "openwebnet_mcp.server"],
"cwd": "/path/to/openwebnet-mcp"
}
}
}Related MCP server: websearch-mcp
🤖 Agentic Interaction Examples
Once connected, your AI coding assistant can browse documentation, interpret frames, and generate verified code autonomously.
Example 1: Decode a Bus Monitor Frame
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).
Example 2: Configure CEN+ Scenario Pushbuttons
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.
Example 3: Solve Light Transition Inconsistencies
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.
🛠️ Tools & Resources Reference
MCP Tools (15)
Tool | Description |
| Ranked keyword and fuzzy search across all protocol specs, guides, and design docs. |
| Retrieve full technical specification, WHAT commands, and DIMENSIONS for a WHO family. |
| Summary inventory table of all 20+ OpenWebNet WHO families with archive status. |
| Full markdown guide for configuring and troubleshooting Home Assistant MyHOME platforms. |
| Grammar, regex templates, and parameter formats for OpenWebNet message types. |
| Deep syntax and semantic validation of any raw OpenWebNet frame string, enriched with empirical firmware oracle verification. |
| Direct lookup of empirical gateway firmware behavior (MH200N, MyHomeServer1) from live QEMU execution (ACK/NACK, bus telegrams, SHA-256 provenance). |
| Construct and validate a syntactically correct OpenWebNet frame string. |
| Build the WHO=16 frame pair that switches a room's audio source, including which amplifiers the change reaches and how far the evidence for it goes. |
| Generate production-ready Home Assistant configuration YAML for MyHOME entities. |
| Inspect Python AST signatures and docstrings from |
| Ranked search over the Encyclopedia's Machine KB (atomic claims and retrieval chunks). Every hit keeps its epistemic status, applicability, provenance, cautions and open questions. |
| Resolve any Machine KB stable ID ( |
| Which Machine KB snapshot backs the answers: versions, artifact-hash verification, counts. |
| Flush caches and reload all OpenWebNet specifications, documents, AST models, Machine KB, and Firmware Oracle verdicts. |
MCP Resources (6)
URI | Description |
| Read-only catalog of all OpenWebNet WHO families. |
| Read-only formal OpenWebNet grammar, regex patterns, and session specs. |
| Read-only diagnostic summary of the empirical firmware oracle index (gateway platforms, versions, total inputs). |
| Master Table of Contents for all indexed OpenWebNet & MyHOME documentation. |
| Read-only full text of a specific documentation guide. |
| Read-only Machine KB manifest: exact dataset, compatibility versions and artifact hashes. |
MCP Prompts (1)
Prompt / Slash Command | Description |
| Injects authoritative OpenWebNet protocol architecture, WHO subsystem mappings, frame delimiters, modern Home Assistant |
Using /boost in MCP Clients
In Claude Desktop, Cursor, or Antigravity, trigger the prompt by typing /boost or selecting it from the prompt menu:
/boost topic: lightingThe server primes the LLM with strict frame grammar rules, hardware capabilities, and modern Home Assistant configuration standards, eliminating hallucinated syntax.
🧠 Machine KB (Encyclopedia knowledge base)
search_knowledge, get_knowledge_record and get_knowledge_status read the
OpenWebNet Encyclopedia Machine KB
(release machine-kb-v0.1.0), following its consumer guide: manifest first, schema-version check,
SHA-256 verification, stable-ID maps, and every qualification returned with the text.
The KB is located, in order, from OPENWEBNET_KB_PATH (the knowledge directory or an Encyclopedia checkout),
the hash-verified download cache, or a sibling OpenWebNet-Encyclopedia/knowledge checkout (an unverified working tree).
The default uvx install ships without the corpus. Fill the cache with a hash-verified release (no checkout needed);
the tools pick it up on the next call, no restart required:
uvx --from git+https://github.com/OpenWebNet-HA/openwebnet-mcp.git openwebnet-mcp-kb-fetch machine-kb-v0.1.0
# or, from a clone: python -m openwebnet_mcp.kb_fetch machine-kb-v0.1.0Hash mismatches (for example a checkout of a branch newer than the tag) are reported by get_knowledge_status
and logged; set OPENWEBNET_KB_STRICT=1 to refuse to load instead. Without a KB the three tools return a clear
error and the rest of the server is unaffected.
Known 0.1.0 limits, surfaced rather than hidden: 1,120 claim statements are truncated by an upstream rendering
defect (Encyclopedia#37) and point to their
intact source chunk; DALI / WHO 24 is not in the corpus yet. Ranking is lexical (BM25) and is not evidence strength; exact
WHO n / WHAT n / DIMENSION n references in a query get a flat bonus so they outrank documents that merely contain the number.
A live test of kb_fetch against the real release is opt-in: OPENWEBNET_LIVE_TESTS=1 pytest -m network.
🛡️ Empirical Firmware Oracle
The lookup_firmware_verdict tool and parse_and_validate_frame integration provide instant, low-latency inspection of real gateway firmware behavior captured by the own-firmware-oracle project.
Execution Environment: Verdicts reflect live OpenWebNet commands executed inside instrumented QEMU emulators running binary firmware images for BTicino MH200N (
010108) and MyHomeServer1 (028206).Ground Truth Grounding: Each verdict captures:
Exact client session reply:
ACK (*#*1##),NACK (*#*0##),SILENT, or*No client reply*.Dispatched SCS bus telegrams (hex bytes) or confirmation that no bus frames were emitted.
Verdict classification:
OUT (Bus)(physically dispatched to the bus) vsSILENT (Drop)(consumed/dropped internally).Secondary session notifications and status events (
emitted_own).Cryptographic provenance: canonical JSON SHA-256 integrity verification and per-target SHA-256 hashes.
Resolution Order:
OPENWEBNET_ORACLE_INDEXenvironment variable (explicit path tomcp_index.json).Sibling checkout:
../own-firmware-oracle/results/mcp_index.json.Bundled index snapshot:
openwebnet_mcp/data/oracle_index.json.
📚 Master WHO Family Inventory
WHO | Subsystem | Official Title | Status | HA Platform |
0 | Scenarios (Basic) |
| 🟢 Archived |
|
1 | Lighting |
| 🟢 Archived |
|
2 | Automation (Covers) |
| 🟢 Archived |
|
3 | Load Control |
| 🟡 Legacy |
|
4 | Thermoregulation |
| 🟢 Archived |
|
5 | Burglar Alarm |
| 🟢 Archived |
|
6 | Door Entry Call & Lock |
| 🟡 Legacy |
|
7 | Video Door Entry |
| 🟢 Archived |
|
9 | Auxiliary |
| 🟡 Legacy |
|
13 | Gateway Management |
| 🟢 Archived | Diagnostics |
14 | Actuators & Lock | (Reverse-Engineered) | 🟢 Documented | Diagnostics, |
15 | CEN Pushbuttons |
| 🟢 Archived |
|
16 | Sound System |
| 🟢 Archived |
|
17 | MH200N Scenarios |
| 🟢 Archived |
|
18 | Energy Management |
| 🟢 Archived |
|
22 | Sound Diffusion (Ext) |
| 🟢 Archived |
|
24 | Lighting / DALI |
| 🟢 Archived |
|
25 | CEN+ / Dry Contacts |
| 🟢 Archived |
|
1001 | Bus Diagnostics |
| 🟢 Archived | Diagnostics |
1004 | Heating Diagnostics |
| 🟢 Archived | Diagnostics |
1013 | Gateway Diagnostics |
| 🟢 Archived | Diagnostics |
🧪 Testing
Run unit tests and verify coverage with pytest:
pip install -e ".[dev]"
pytest --cov=src/openwebnet_mcp --cov-report=term-missing📄 License
Apache License 2.0, the same license as Home Assistant Core. See LICENSE. Copyright (c) 2026 OpenWebNet-HA Community.
Available Tools
10 toolsdraft_ha_configDraft Ha ConfigA
Generate production-ready Home Assistant YAML configuration for any MyHOME entity.
Inputs: name (required), where (required), platform (required), mac, +9 more. Returns: result
draft_own_frameDraft Own FrameC
Construct and validate a syntactically correct OpenWebNet frame.
Inputs: who (required), where (required), command_type (required), what, +2 more. Returns: result
get_code_signatureGet Code SignatureB
Inspect Python AST signatures, public methods, and docstrings from custom_components/myhome or OWNd.
Inputs: symbol (required). Returns: result
get_ha_guideGet Ha GuideB
Fetch complete markdown guide for configuring and troubleshooting Home Assistant entities.
Inputs: topic (required). Returns: result
get_who_specGet Who SpecA
Retrieve full technical specification, WHAT commands, and DIMENSIONS for an OpenWebNet WHO family.
Inputs: who (required). Returns: result
list_who_catalogList Who CatalogA
Return complete inventory table of all 20+ OpenWebNet WHO families with archive status and HA platform.
Inputs: no named parameters. Returns: result
lookup_frame_syntaxLookup Frame SyntaxB
Look up OpenWebNet message grammar, regex templates, and parameter formats.
Inputs: who, frame_type. Returns: result
parse_and_validate_frameParse And Validate FrameA
Parse a raw OpenWebNet frame string and perform semantic protocol validation.
Inputs: frame (required). Returns: result
rescan_documentationRescan DocumentationA
Flush caches and reload all OpenWebNet specifications, markdown documents, and codebase AST models.
Inputs: no named parameters. Returns: result
search_documentationSearch DocumentationA
Fuzzy and keyword search across OpenWebNet protocol specifications and Home Assistant MyHOME guides.
Inputs: query (required), category. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: search, retrieve specs, list catalog, get guide, lookup syntax, parse, draft, generate config, inspect code, and refresh caches. There is no overlap in functionality.
All tools use snake_case with consistent verb-noun patterns (e.g., search_, get_, list_, lookup_, draft_, rescan_). The naming is predictable and uniform.
With 10 tools, the set is well-scoped for a documentation and frame utility server, covering search, retrieval, parsing, drafting, and maintenance without redundancy or bloat.
The surface covers search, spec lookup, catalog listing, guides, syntax reference, parsing/validation, frame drafting, HA config generation, code inspection, and cache management. Minor gaps like a tool for comparing frames or bulk operations exist, but core workflows are complete.
Maintenance
Related MCP Connectors
A real browser for your agent: screenshots, page checks, Markdown and PDFs.
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceEnables comprehensive browser automation and web interaction through Playwright with 50+ specialized functions for navigation, form filling, data extraction, and Chrome DevTools Protocol support. Designed specifically for AI agents to perform complex web workflows including scraping, testing, and automated browsing tasks.14 npm1Apache 2.0- AlicenseAqualityNot gradedmaintenanceEnables web searching via SearXNG, page content extraction with Crawl4AI, and image analysis using vision language models. It provides AI agents with tools for information synthesis and web-based data retrieval through OpenAI-compatible LLM endpoints.3Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to crawl, scrape, search, and automate browsers with anti-bot bypass, providing fast web access via 22 tools.22316 npm3MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to control a browser through tools for navigation, typing, clicking, and taking screenshots to perform web automation tasks.Apache 2.0