echonetlite-mcp

An MCP (Model Context Protocol) server for ECHONETLite home automation — control air conditioners 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

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

• 📦 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

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

Device Discovery

HVAC Control

Sensor Readings

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"

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

Project Structure

echonetlite-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── echonetlite.ts        # ECHONETLite client wrapper
│   ├── devices/
│   │   └── homeAirConditioner.ts  # HVAC device handler
│   ├── types.ts              # TypeScript type definitions
│   └── config.ts             # Configuration constants
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

Development

# Clone and install dependencies
git clone https://github.com/scottyphillips/echonetlite-mcp.git
cd echonetlite-mcp
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Run the server
node dist/index.js

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.