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"
    }
  }
}

🤖 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 (10)

MCP Resources (4)

MCP Prompts (1)

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.

📚 Master WHO Family Inventory

🧪 Testing

Run unit tests and verify coverage with pytest:

pip install -e ".[dev]"
pytest --cov=src/openwebnet_mcp --cov-report=term-missing

📄 License

MIT License. Copyright (c) 2026 OpenWebNet-HA Community.