Documentation

Complete guide to Loxone AI — control your smart home via Claude and other AI assistants using the MCP protocol.

Quick Start

Get started with Loxone AI in 3 steps:

Requirements

• Loxone Miniserver (Gen 1 or Gen 2) accessible over the network
• Claude Desktop, Claude.ai, Cursor, Windsurf, or any MCP-compatible client
• Network access between the Loxone Miniserver and the internet (for cloud mode)

Supported platforms

• macOS 12+ (Apple Silicon and Intel)
• Windows 10/11
• Linux (Docker)

Cloud MCP

The Cloud MCP server runs on our infrastructure at https://cloud.loxoneai.com/cloud/mcp. Your Loxone credentials are stored encrypted in our database — no software installation needed on your machine.

• Works from anywhere — no local network required
• Available for all registered users
• Supports Claude.ai (web), Claude Desktop, Cursor, Windsurf, and more
• All traffic encrypted via HTTPS / OAuth 2.0

Authentication

The Cloud MCP server uses OAuth 2.0. The authorization server is https://loxoneai.com.

• Authorization Code + PKCE — for Claude.ai web and apps that open a browser window
• Client Credentials — for headless clients (Claude Desktop, Cursor, Windsurf) using a Bearer token

Get your access token or OAuth credentials from the Dashboard → API Keys tab.

App Configuration

Configurations for supported applications:

Claude.ai (web)

Uses the OAuth Authorization Code flow — no manual config needed. In the Dashboard, click Connect to Claude.ai and authorize in your browser.

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "loxone-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://cloud.loxoneai.com/cloud/mcp",
        "--header", "Authorization: Bearer YOUR_ACCESS_TOKEN"]
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "loxone-cloud": {
      "url": "https://cloud.loxoneai.com/cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "loxone-cloud": {
      "serverUrl": "https://cloud.loxoneai.com/cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Continue

Config file: ~/.continue/config.yaml

mcpServers:
  - name: loxone-cloud
    url: https://cloud.loxoneai.com/cloud/mcp
    requestOptions:
      headers:
        Authorization: "Bearer YOUR_ACCESS_TOKEN"

Cline

{
  "mcpServers": {
    "loxone-cloud": {
      "url": "https://cloud.loxoneai.com/cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Custom app / API

Get an access token via OAuth 2.0 Client Credentials:

curl -X POST https://loxoneai.com/oauth/token \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_SECRET"

Then pass the token as Authorization: Bearer ACCESS_TOKEN to the MCP endpoint.

Loxone Cloud URL

If your Miniserver is on Loxone Cloud (not a local IP), use:

connect.loxonecloud.com/YOUR_MAC_ADDRESS

Find the MAC address in Loxone Config or the Loxone App.

Local MCP

The Local MCP server runs directly on your machine and connects to the Loxone Miniserver over your local network. Your credentials never leave your home — everything runs offline.

• Fully offline — no internet connection required after setup
• Lower latency — direct connection to Miniserver
• Available for all registered users
• Supports macOS, Windows, and Docker

macOS / Windows installer

Docker

Run the Local MCP server as a Docker container. Find your license key in the Dashboard:

docker run -d \
  -e LICENSE_KEY=YOUR_LICENSE_KEY \
  -p 8080:8080 \
  loxoneai/loxone-mcp:latest

Claude Desktop config for Docker:

{
  "mcpServers": {
    "loxone": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Working Examples

These examples demonstrate core functionality of the Loxone AI MCP server. Each shows the natural language prompt sent to the AI, the MCP tool call made, and the expected response.

"Turn on the lights in the living room"

{
  "tool": "loxone_light_on",
  "arguments": {
    "control": "Living Room"
  }
}

{
  "success": true,
  "message": "Light turned on: Living Room",
  "device": "Living Room",
  "action": "on"
}

"What is the temperature in the bedroom?"

{
  "tool": "loxone_get_temperature",
  "arguments": {
    "room": "Bedroom"
  }
}

{
  "room": "Bedroom",
  "temperature_c": 21.4,
  "unit": "°C",
  "sensor": "Temperature Bedroom"
}

"Close the blinds in the living room"

{
  "tool": "loxone_blind_down",
  "arguments": {
    "control": "Living Room"
  }
}

{
  "success": true,
  "message": "Blind moved down: Living Room",
  "device": "Living Room",
  "action": "down"
}

"Show me all devices in my home"

{
  "tool": "loxone_list_devices",
  "arguments": {}
}

{
  "lights": [
    { "name": "Living Room", "room": "Living Room", "type": "LightControllerV2" },
    { "name": "Kitchen", "room": "Kitchen", "type": "Dimmer" }
  ],
  "blinds": [
    { "name": "Blind Living Room", "room": "Living Room", "type": "Jalousie" }
  ],
  "gates": [
    { "name": "Garage Door", "room": "Garage", "type": "Gate" }
  ],
  "thermostats": [
    { "name": "Temperature Bedroom", "room": "Bedroom", "type": "InfoOnlyAnalog" }
  ]
}

"Dim the bedroom lights to 30%"

{
  "tool": "loxone_dimmer",
  "arguments": {
    "control": "Bedroom",
    "value": 30
  }
}

{
  "success": true,
  "message": "Dimmer set to 30%: Bedroom",
  "device": "Bedroom",
  "value": 30
}

Natural Language Commands

Loxone AI understands natural language. Here are example prompts you can use:

Lights

"Turn on the living room lights"
"Turn off all lights"
"Dim the bedroom lights to 30%"
"Set the kitchen light to 80%"
"What lights are currently on?"

Blinds & shutters

"Close the blinds in the living room"
"Open all blinds"
"Set blinds to 50%"
"Close the shutters in the bedroom"

Temperature

"What is the temperature in the living room?"
"Show temperatures in all rooms"
"Which room is the warmest?"

Gates & garage

"Open the garage door"
"Close the entrance gate"

Devices

"Show all devices"
"What devices are in the kitchen?"
"List all lights"

Supported Devices

MCP Tools Reference

The Loxone AI MCP server exposes 32 tools. Key tools:

loxone_list_devices

Returns all devices grouped by category (lights, blinds, gates, thermostats, presence, sensors).

loxone_light_on / loxone_light_off

Turn a light or room on/off. Parameter: control — device or room name.

loxone_dimmer

Set light brightness. Parameters: control (device/room), value (0–100).

loxone_blind_up / loxone_blind_down

Fully open or close a blind. Parameter: control — device or room name.

loxone_blind_position

Set blind to a specific position. Parameters: control, position (0=open, 100=closed).

loxone_get_temperature

Read current temperature from a room sensor. Parameter: room.

loxone_get_room_climate

Get full climate overview for a room: temperature, humidity, target temperature, thermostat mode.

loxone_get_room_summary

Complete room overview: all lights, blinds, temperature, humidity, presence.

loxone_get_all_lights_status

On/off/dimmer status of all lights in the entire home, grouped by room.

loxone_gate_open / loxone_gate_close

Open or close a gate or garage door. Parameter: control.

loxone_get_weather

Outdoor weather: temperature, wind speed, rain, brightness, storm warnings.

loxone_get_energy

Energy consumption and production data (grid, solar PV, battery).

Troubleshooting

Claude doesn't see Loxone tools

Cannot connect to Loxone

Devices not found

Cloud access not working