Loxone MCP Server

Bridging Loxone home automation with the Model Context Protocol ecosystem through high-performance Rust implementation

A Model Context Protocol (MCP) server that enables programmatic control of Loxone home automation systems. This implementation provides comprehensive device control through 17 specialized tools and 25+ resources, supporting both stdio (for Claude Desktop) and HTTP transports.

Features

• Comprehensive Control: 17 MCP tools for device control + 25+ resources for data access
• MCP Compliant: Proper separation of tools (actions) and resources (read-only data)
• Multiple Transports: stdio for Claude Desktop, HTTP/SSE for web integrations
• Enhanced Security: Framework-based authentication with advanced features
• Performance Optimized: Connection pooling, intelligent caching, batch operations
• Framework Integration: Built on PulseEngine MCP framework for standardized protocol handling

Requirements

• Rust 1.70 or higher
• Loxone Miniserver (Gen 1 or Gen 2)
• Network access to Miniserver

Installation

From Source

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

Configuration

🆕 Credential ID System (Recommended)

1. Quick Setup with Credential ID:

   # Interactive setup with ID generation
   cargo run --bin loxone-mcp-setup --generate-id --name "Main House"
   
   # Store credentials manually
   cargo run --bin loxone-mcp-auth store \
     --name "Office" \
     --host 192.168.1.100 \
     --username admin \
     --password secure123

2. Manage Multiple Servers:

   # List stored credentials
   cargo run --bin loxone-mcp-auth list
   
   # Test connections
   cargo run --bin loxone-mcp-auth test <credential-id>

Legacy Environment Variables

1. Basic Setup:

   cargo run --bin loxone-mcp-setup

2. Environment variables:

   export LOXONE_HOST="http://192.168.1.100"
   export LOXONE_USER="your-username"
   export LOXONE_PASS="your-password"

3. Production with Infisical (optional):

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

🔄 Migration from Environment Variables

If you're currently using environment variables, see the Credential Migration Guide for step-by-step instructions to migrate to the new Credential ID system.

Usage

Claude Desktop Integration

With Credential ID (Recommended)

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

Legacy Environment Variables

{
  "mcpServers": {
    "loxone": {
      "command": "/path/to/loxone-mcp-server",
      "args": ["stdio"],
      "env": {
        "LOXONE_HOST": "192.168.1.100",
        "LOXONE_USER": "admin",
        "LOXONE_PASS": "password"
      }
    }
  }
}

HTTP Server (for n8n, web clients)

With Credential ID

cargo run --bin loxone-mcp-server http --port 3001 --credential-id abc123def-456-789

Legacy Mode

cargo run --bin loxone-mcp-server http --port 3001

Verify Installation

# Test with credential ID
cargo run --bin loxone-mcp-auth test <credential-id>

# Or list available credentials
cargo run --bin loxone-mcp-auth list

Available Tools & Resources

The server implements 17 tools for actions and 25+ resources for data access:

Tools (Actions)

• Device Control: control_device, control_multiple_devices
• Lighting: control_lights_unified, control_all_lights, control_room_lights
• Blinds/Rolladen: control_rolladen_unified, control_all_rolladen, control_room_rolladen, discover_rolladen_capabilities
• Climate: set_room_temperature, set_room_mode
• Audio: control_audio_zone, set_audio_volume
• Security: arm_alarm, disarm_alarm
• Workflows: create_workflow, execute_workflow_demo

Resources (Read-Only Data)

• Rooms: loxone://rooms, loxone://rooms/{room}/devices, loxone://rooms/{room}/overview
• Devices: loxone://devices/all, loxone://devices/category/{category}, loxone://devices/type/{type}
• System: loxone://system/status, loxone://system/capabilities, loxone://system/categories
• Sensors: loxone://sensors/door-window, loxone://sensors/temperature, loxone://sensors/motion
• Audio: loxone://audio/zones, loxone://audio/sources
• And more... (weather, energy, security, climate)

Full tool documentation → | Resource documentation →

Architecture

The server uses an async Rust architecture with:

• Transport Layer: Supports stdio and HTTP/SSE
• Tool Layer: Modular tool implementations
• Client Layer: HTTP and WebSocket clients for Miniserver communication
• Security Layer: Authentication, rate limiting, input validation
• Cache Layer: Intelligent state caching with TTL

Architecture details →

Security

• Framework Authentication: Enhanced security with PulseEngine MCP v0.4.0
  • API Key Management with role-based permissions
  • JWT tokens for stateless sessions
  • Encrypted storage with AES-GCM
  • Vault integration (Infisical support)
  • 8 predefined security profiles
• Rate Limiting: Configurable per-role limits
• Input Validation: All inputs sanitized and validated
• Audit Logging: Comprehensive activity logging

Security documentation →

Development

Building from Source

# Development build with debug symbols
cargo build

# Run tests
cargo test

# Format and lint
cargo fmt && cargo clippy

Project Structure

src/
├── server/          # MCP protocol implementation
├── tools/           # Tool implementations
├── client/          # Loxone client
├── security/        # Auth and validation
└── main.rs          # Entry point

Limitations

• WASM Support: Currently disabled due to tokio compatibility issues
• Real-time Updates: WebSocket subscriptions planned but not yet implemented
• Miniserver Version: Tested with Gen 1 and Gen 2, newer versions may have differences

Contributing

Contributions are welcome! Please see contributing.md for guidelines.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Acknowledgments

Built on the PulseEngine MCP framework. Special thanks to the Loxone community for protocol documentation.