loxone-mcp

An MCP (Model Context Protocol) server that connects AI assistants to a Loxone Miniserver smart home system.

Lets Claude (or any MCP-compatible AI) list rooms, query live sensor/actuator states, search devices, and send commands.

Features

• list_rooms — all rooms with their controls
• list_controls — all controls (name, type, UUID, room)
• find_control — keyword search across name/room/type
• get_status — live sensor and actuator values (optional room filter)
• control_device — send commands (On/Off, dimmer %, blinds, HVAC, audio)

Requirements

• Loxone Miniserver with Cloud Connect enabled
• Node.js 20+ (or Docker)

Installation

npm

npm install -g @syntropic/loxone-mcp

Then run with environment variables set:

LOXONE_SERIAL=XXXXXXXXXXXX \
LOXONE_USER=admin \
LOXONE_PASS=yourpass \
MCP_API_KEY=$(openssl rand -hex 32) \
loxone-mcp

From source

git clone https://github.com/syntropicsignal-ai/loxone-mcp.git
cd loxone-mcp
cp .env.example .env
# edit .env with your Miniserver serial, credentials, and a random API key
npm install
npm run build
npm start

The server listens on http://localhost:3000. The MCP endpoint is POST /mcp.

Docker

docker build -t loxone-mcp .
docker run -p 3000:3000 --env-file .env loxone-mcp

Configuration

| Variable | Required | Description | |----------|----------|-------------| | LOXONE_SERIAL | Yes | 12-char Miniserver serial (from Loxone Config → Miniserver) | | LOXONE_USER | Yes | Miniserver username | | LOXONE_PASS | Yes | Miniserver password | | MCP_API_KEY | Yes | Bearer token for MCP endpoint auth (openssl rand -hex 32) | | PORT | No | HTTP port (default: 3000) |

Connecting to Claude

Add to your Claude MCP configuration:

{
  "mcpServers": {
    "loxone": {
      "url": "https://your-server/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

Supported commands by device type

| Type | Commands | |------|----------| | Switch / Light | On, Off, pulse | | Dimmer | On, Off, value/50 (0–100%), Up, Down | | Jalousie (blinds) | Up, Down, Stop, FullUp, FullDown, shade | | Gate | Open, Close, Stop | | HVAC (IRoomControllerV2) | setComfortTemperature/21.5, override/1/22/3600 | | AudioZone | play, pause, stop, volume/50 |

Architecture

• Stateless HTTP server — each POST /mcp creates a fresh transport (no session state)
• Loxone Cloud Connect: resolves current tunnel URL via dns.loxonecloud.com on every request
• Structure cache: Loxone app structure (LoxAPP3.json) cached for 60 seconds

License

MIT