Skip to main content
Glama

OpenWebNet-MCP Server

CI Pipeline Platform Validation Python Support License

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:

  1. Calls parse_and_validate_frame("*#4*1*#14*0215*1##").

  2. Resolves WHO=4 (Heating/Thermoregulation), Dimension 14 (Target Temperature & Mode), Zone 1, Target 21.5°C, Mode 1 (Heating).

  3. 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:

  1. Calls get_ha_guide("cen_scenarios") to review the CEN vs CEN+ specifications and Home Assistant blueprint.

  2. 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##.

  3. 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:

  1. Calls search_documentation("transition stepped dimming").

  2. Reads the technical design document explaining hardware ramp limitations in older F411/F418 actuators vs software-emulated stepped dimming.

  3. Suggests the proper configuration and command sequence.


🛠️ Tools & Resources Reference

MCP Tools (15)

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, enriched with empirical firmware oracle verification.

lookup_firmware_verdict

Direct lookup of empirical gateway firmware behavior (MH200N, MyHomeServer1) from live QEMU execution (ACK/NACK, bus telegrams, SHA-256 provenance).

draft_own_frame

Construct and validate a syntactically correct OpenWebNet frame string.

draft_sound_source_selection

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.

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.

search_knowledge

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.

get_knowledge_record

Resolve any Machine KB stable ID (ownkb:claim:…, ownkb:chunk:…, ownkb:caution:…, …) with cautions and questions hydrated.

get_knowledge_status

Which Machine KB snapshot backs the answers: versions, artifact-hash verification, counts.

rescan_documentation

Flush caches and reload all OpenWebNet specifications, documents, AST models, Machine KB, and Firmware Oracle verdicts.

MCP Resources (6)

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.

oracle://index

Read-only diagnostic summary of the empirical firmware oracle index (gateway platforms, versions, total inputs).

docs://toc

Master Table of Contents for all indexed OpenWebNet & MyHOME documentation.

docs://guide/{topic}

Read-only full text of a specific documentation guide.

kb://manifest

Read-only Machine KB manifest: exact dataset, compatibility versions and artifact hashes.

MCP Prompts (1)

Prompt / Slash Command

Description

/boost [topic]

Injects authoritative OpenWebNet protocol architecture, WHO subsystem mappings, frame delimiters, modern Home Assistant /config/myhome.yaml standards, and firmware verdict guidance directly into the AI agent context window.

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: lighting

The 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.0

Hash 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) vs SILENT (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:

    1. OPENWEBNET_ORACLE_INDEX environment variable (explicit path to mcp_index.json).

    2. Sibling checkout: ../own-firmware-oracle/results/mcp_index.json.

    3. Bundled index snapshot: openwebnet_mcp/data/oracle_index.json.


📚 Master WHO Family Inventory

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


🧪 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 tools
draft_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

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools use snake_case with consistent verb-noun patterns (e.g., search_, get_, list_, lookup_, draft_, rescan_). The naming is predictable and uniform.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      1
      Apache 2.0
    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables 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.
      3
      Apache 2.0