echonetlite-mcp

An MCP (Model Context Protocol) server for ECHONETLite home automation — control air conditioners, discover devices, and read sensors via the Model Context Protocol.

ECHONETLite is a Japanese IoT protocol widely used in smart home devices, particularly HVAC systems by major manufacturers like Daikin, Panasonic, Mitsubishi Electric, and Toshiba.

Features

• 🌡️ Real-time HVAC monitoring — temperature, humidity, operating status

• ❄️ Full climate control — mode, fan speed, airflow direction, swing

• 🔍 Network device discovery — find ECHONETLite devices via multicast UDP

• 🔬 Node Profile probing — discover manufacturer, product code, UID, and all EOJ instances on any device

• ⚡ Real-time notifications — async updates from device multicast listeners

• 📖 MRA enrichment — Machine Readable Index integration for property names, descriptions, and value decoding

• 🔬 EPC introspection — query property maps (STATMAP/SETMAP/GETMAP) with MRA-based names

• 🏷️ Human-readable values — raw EPC values decoded to human-friendly format using MRA definitions

• 🧩 EPC element parsing — parse complex object/array-type EPC values into named elements with MRA definitions

• 🎯 Multi-EPC queries — query multiple EPC codes in a single request

• 🔧 Generic EOJ support — set/query any ECHONETLite object by group/class/instance codes

• 📦 TypeScript-first — full type definitions included

• 🔌 MCP compatible — works with any MCP client (Claude Desktop, LM Studio, VS Code extensions, etc.)

Related MCP server: OXII Smart Home MCP Server

Prerequisites

• Node.js 18+

• An ECHONETLite-compatible device on the same local network

Installation

npm install echonetlite-mcp

Or use it as an MCP server directly:

git clone https://github.com/scottyphillips/echonetlite-mcp.git
cd echonetlite-mcp
npm install
npm run build

Configuration

The server defaults to communicating with a device at 192.168.1.6 on UDP port 3610, using multicast address 224.0.23.0:3610 for discovery and notifications.

Setting the Default Device IP

Option A: Environment variable (recommended)

# Windows CMD
set ECHONET_DEFAULT_HOST=192.168.1.10 && node dist/index.js

# PowerShell
$env:ECHONET_DEFAULT_HOST="192.168.1.10"; node dist/index.js

# Linux/macOS
ECHONET_DEFAULT_HOST=192.168.1.10 node dist/index.js

Option B: Edit config.ts

export const DEFAULT_HOST = '192.168.1.10';  // Change to your device IP

Lite Mode (Restricted Tool Set)

Enable Lite Mode to restrict exposed tools to a minimal subset. In lite mode, only these 6 tools are available:

All HVAC-specific tools (get_device_status, set_operation, set_temperature, etc.) are hidden in lite mode.

Enable Lite Mode:

# Windows CMD
set ECHONET_LITE_MODE=true && node dist/index.js

# PowerShell
$env:ECHONET_LITE_MODE="true"; node dist/index.js

# Linux/macOS
ECHONET_LITE_MODE=true node dist/index.js

When lite mode is enabled, the server logs (Mode: LITE) on startup. When disabled (default), it logs (Mode: FULL) with all tools available.

Per-Tool Override

Every tool accepts an optional host parameter to override the default for that specific call:

{ "name": "get_device_status", "arguments": { "host": "192.168.1.20" } }

Running the Server

# Build first
npm run build

# Run (stdio transport)
node dist/index.js

The server communicates via stdio, making it compatible with any MCP client.

Integration with AI Clients

Claude Desktop

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "echonetlite": {
      "command": "node",
      "args": ["/path/to/echonetlite-mcp/dist/index.js"],
      "env": {
        "ECHONET_DEFAULT_HOST": "192.168.1.6"
      }
    }
  }
}

LM Studio

LM Studio supports MCP servers via stdio transport. Create or edit the MCP config file:

Windows: %APPDATA%\lm-studio\mcp_config.json macOS/Linux: ~/.config/lm-studio/mcp_config.json

{
  "mcpServers": {
    "echonetlite-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\echonetlite-mcp\\dist/index.js"],
      "env": {
        "ECHONET_DEFAULT_HOST": "192.168.1.6"
      }
    }
  }
}

VS Code MCP Extension

Configure in your VS Code MCP extension settings:

{
  "mcp.servers": [
    {
      "name": "echonetlite",
      "command": "node",
      "args": ["/path/to/echonetlite-mcp/dist/index.js"],
      "env": {
        "ECHONET_DEFAULT_HOST": "192.168.1.6"
      }
    }
  ]
}

Available Tools

Note: When ECHONET_LITE_MODE=true, only discover_devices, discover_nodes, set_epc, get_property_maps, query_epc, and get_epc_definition are available.

Device Discovery

HVAC Control (Full Mode Only)

Sensor Readings (Full Mode Only)

EPC Introspection & MRA Lookup (Available in All Modes)

Available Resources

EPC Reference Table

Example Prompts

Try these natural language prompts with your MCP client:

• "Turn on my air conditioner" → calls set_operation with operation="on" (Full Mode)

• "Set temperature to 23 degrees" → calls set_temperature with temperature=23

• "Switch to cooling mode" → calls set_operating_mode with mode="cool"

• "What are the current temperatures?" → calls get_temperatures

• "Find all ECHONET devices on my network" → calls discover_devices

• "Set fan speed to level 3" → calls set_fan_speed with speed="level3"

• "What EPC codes can I query on this device?" → calls get_property_maps

• "Get the current operation status and target temperature" → calls query_epc with epcs=["0x80", "0xB3"]

• "What settings are available for operating mode?" → calls get_epc_definition with epcs=["0xB0"]

• "Discover all nodes on 192.168.1.6" → calls discover_nodes with full MRA enrichment

• "Parse the EPC 0xE2 value 0x00 0x0A 0xFF 0xFF for EOJ 0x02 0x88 0x01" → calls parse_epc_elements to split raw bytes into named elements

Project Structure

echonetlite-mcp/
├── src/
│   ├── index.ts              # MCP server entry point & tool definitions (~1200 lines)
node dist/index.js

MRA Integration

This server includes full MRA (Machine Readable Index) data integration:

• Property names & descriptions — human-readable labels for each EPC code from MRA definitions

• Value decoding — raw hex values decoded to meaningful strings/numbers using MRA type schemas

• Enum/bitmap support — full enumeration of possible values with $ref resolution

• Level ranges & number formats — signed/unsigned integers, fixed-point decimals

• $ref resolution — external definition references from definitions.json resolved automatically

• MRA enrichment in all tools — query_epc, get_property_maps, get_epc_definition return enriched responses

The MRA data enables intelligent discovery of what settings are available for any EPC code without needing to query the device first.

References

• ECHONETLite Standard Spec

• MCP Specification

• node-echonet-lite

• pychonet

License

MIT License — see LICENSE for details.

Support

For issues, questions, or contributions, please open an issue on GitHub.