🏠 Loxone MCP Server

Control your Loxone smart home through the Model Context Protocol

 

 

An async Rust MCP server that connects AI assistants to Loxone Miniservers. Control lights, blinds, climate, security, audio, and more — all through standardized MCP tools and resources.

[!NOTE] Built on the PulseEngine MCP framework v0.17.0 for standardized protocol handling, authentication, and transport layers.

Features

• 🔌 17 MCP Tools — Control lights, blinds, HVAC, security, audio, door locks, intercoms, and scenes — all wired to real Miniserver commands
• 📊 25+ MCP Resources — Read-only access to rooms, devices, sensors, energy, weather, and system status with live state
• 🚀 Three Transports — stdio (Claude Desktop), HTTP/SSE (n8n, web clients), and Streamable HTTP
• 🔐 Security by Default — SSL verification on, UUID validation, rate limiting, input sanitization, dev-mode restricted to localhost
• ⚡ Async Rust — Connection pooling, intelligent caching, batch operations
• 🧊 Nix Flake — Reproducible builds with OpenClaw plugin integration
• 🔑 Credential Management — Credential ID system, environment variables, or Infisical vault

Quick Start

# Build
cargo build --release

# Setup credentials
cargo run --bin loxone-mcp-setup -- --generate-id --name "My Home"

# Run with Claude Desktop
cargo run --bin loxone-mcp-server -- stdio --credential-id <your-id>

Installation

From Source

git clone https://github.com/avrabe/mcp-loxone
cd mcp-loxone
cargo build --release

Nix Flake

nix build github:avrabe/mcp-loxone
# Or run directly
nix run github:avrabe/mcp-loxone

Docker

docker build -t loxone-mcp .
docker run -e LOXONE_HOST=192.168.1.100 \
           -e LOXONE_USER=admin \
           -e LOXONE_PASS=secret \
           -p 3001:3001 loxone-mcp

Configuration

Credential ID (Recommended)

# Interactive setup — generates a unique credential ID
cargo run --bin loxone-mcp-setup -- --generate-id --name "Main House"

# Or store manually
cargo run --bin loxone-mcp-auth -- store \
  --name "Office" --host 192.168.1.100 \
  --username admin --password secure123

# Manage credentials
cargo run --bin loxone-mcp-auth -- list
cargo run --bin loxone-mcp-auth -- test <credential-id>

Environment Variables

export LOXONE_HOST="192.168.1.100"
export LOXONE_USER="admin"
export LOXONE_PASS="password"

Infisical Vault (Production)

export INFISICAL_PROJECT_ID="your-project-id"
export INFISICAL_CLIENT_ID="your-client-id"
export INFISICAL_CLIENT_SECRET="your-client-secret"

[!TIP] Migrating from environment variables? See the Credential Migration Guide.

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "loxone": {
      "command": "loxone-mcp-server",
      "args": ["stdio", "--credential-id", "abc123def-456-789"]
    }
  }
}

HTTP Server (n8n, MCP Inspector)

# Standard HTTP/SSE
loxone-mcp-server http --port 3001 --credential-id <id>

# Streamable HTTP (new MCP Inspector)
loxone-mcp-server streamable-http --port 3001 --credential-id <id>

OpenClaw Integration

The flake exports an openclawPlugin for nix-openclaw:

customPlugins = [
  {
    source = "github:avrabe/mcp-loxone";
    config.env = {
      LOXONE_HOST = "/path/to/secrets/loxone-host";
      LOXONE_USER = "/path/to/secrets/loxone-user";
      LOXONE_PASS = "/path/to/secrets/loxone-pass";
    };
  }
];

Tools & Resources

Tools (Actions)

Category	Tools	Description
Lighting	control_light	On/off, dim 0-100%
Blinds	control_blind	Up/down/stop, position 0-100%
Climate	set_temperature	Target temperature with safe range validation
Security	set_security_mode	Arm, disarm, night, away modes
Doors	control_door_lock	Lock, unlock, open
Intercom	control_intercom	Answer, decline, open door
Audio	control_audio	Play, pause, volume per zone
Scenes	activate_scene	Trigger named scenes
General	control_device, get_*_status	Direct device control, live status queries

Resources (Read-Only)

URI Pattern	Data
loxone://rooms	Room listing with device counts
loxone://rooms/{room}/devices	Devices in a specific room
loxone://devices/all	Full device inventory
loxone://devices/category/{cat}	Devices by category
loxone://sensors/*	Door/window, temperature, motion
loxone://audio/zones	Audio zone configuration
loxone://system/status	Miniserver status and capabilities
loxone://energy/*	Power monitoring and consumption

Architecture

AI Assistant (Claude, n8n, OpenClaw)
        │
   MCP Protocol (stdio / HTTP / Streamable HTTP)
        │
   ┌────▼─────────────────────────┐
   │   loxone-mcp-server          │
   │  ┌─────────────────────────┐ │
   │  │ Security Layer          │ │
   │  │ Auth · Rate Limit · TLS │ │
   │  ├─────────────────────────┤ │
   │  │ Tool Handlers           │ │
   │  │ 17 tools → send_command │ │
   │  ├─────────────────────────┤ │
   │  │ Loxone Client           │ │
   │  │ HTTP · WebSocket · Cache│ │
   │  └─────────────────────────┘ │
   └────┬─────────────────────────┘
        │
   HTTP /jdev/sps/io/{uuid}/{cmd}
        │
   Loxone Miniserver
        │
   Physical Devices

Development

Requirements

• Rust 1.85+ (2024 edition)
• Loxone Miniserver (Gen 1 or Gen 2)

Building & Testing

cargo build                                    # Dev build
cargo test --lib                               # Unit tests
cargo fmt && cargo clippy -- -D warnings       # Format + lint
cargo audit                                    # Security audit

Live Miniserver Testing

# Requires network access to Miniserver
LOXONE_LIVE_TEST=1 cargo test \
  --test live_miniserver_tests \
  --features test-utils -- --nocapture

Project Structure

src/
├── server/          # MCP protocol, tool handlers (macro_backend.rs)
├── client/          # HTTP/WebSocket clients with UUID validation
├── config/          # Credentials, master key auto-persistence
├── security/        # Input sanitization, rate limiting, CORS
├── monitoring/      # Metrics, dashboards, InfluxDB
├── history/         # Time-series data storage
├── discovery/       # mDNS network discovery
└── main.rs          # CLI, transport selection, startup

Binaries

Binary	Purpose
loxone-mcp-server	Main MCP server (stdio/HTTP/streamable-http)
loxone-mcp-auth	Credential management (store, list, test, delete)
loxone-mcp-setup	Interactive setup with credential ID generation
loxone-mcp-test-endpoints	API endpoint testing (development)

License

Licensed under either of:

• MIT License
• Apache License 2.0

at your option.

 

Built on PulseEngine MCP framework — async Rust for the Model Context Protocol