Loxone MCP Server

A Model Context Protocol (MCP) server that connects AI assistants and IDEs to your Loxone smart home system. Control lights, blinds, climate, and scenes through natural language or code.

What it does

• Device Control: Turn lights on/off, adjust dimmers, control blinds and climate

• Scene Management: Trigger Loxone scenes and automation scenarios

• Real-time Updates: Live device state monitoring via WebSocket

• Secure Access: PIN-protected commands for security devices

• Auto Discovery: Finds all your Loxone devices automatically

Requirements

• Python 3.10+

• Loxone Miniserver (Gen 1/2, firmware 10.0+)

• Network access to your Miniserver

• Valid Miniserver credentials

Local Setup

Install uv (Python package manager)

Install and run the server

Configuration

The server is stateless and does not require environment credentials. Each MCP client provides credentials when calling tools.

Optional server configuration:

Running the MCP Server

The server supports two transport modes:

1. Stdio Mode (Default)

For MCP clients like Claude Desktop that connect via stdio:

2. HTTP Mode

For web-based clients or Amazon Q CLI that connect via HTTP:

Amazon Q CLI MCP Configuration

Setup Amazon Q CLI Agent (Stdio Mode)

The project includes a pre-configured Amazon Q CLI agent:

The agent configuration is in .amazonq/cli-agents/loxone-agent.json and includes:

• MCP server setup with uv runner

• Allowed tools for safe operation

• Resource access to docs and config files

Note: Credentials are now provided per tool call, not stored in settings.

Setup Amazon Q CLI with HTTP Transport

To use Amazon Q CLI with HTTP transport, run the server in one console and configure Q CLI to connect via HTTP:

Console 1 - Start the HTTP server:

Console 2 - Configure Amazon Q CLI:

Using with Other MCP Clients

Claude Desktop (Stdio Mode)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

Claude Desktop (HTTP Mode)

For HTTP mode, start the server separately and configure Claude Desktop to connect via HTTP:

1. Start the server in HTTP mode:

2. Configure Claude Desktop for HTTP:

Other MCP Clients

• Stdio mode: Use the command-line pattern shown above

• HTTP mode: Connect to http://127.0.0.1:8000/mcp endpoint

Available MCP Tools

The server provides these tools for AI assistants. All tools require Miniserver credentials as parameters:

• loxone_list_devices - List all devices (requires: host, username, password)

• loxone_get_device_state - Get current device state (requires: host, username, password, uuid)

• loxone_set_switch - Turn switches on/off (requires: host, username, password, uuid, state)

• loxone_set_dimmer - Control light brightness (requires: host, username, password, uuid, brightness)

• loxone_set_cover_position - Control blinds/covers (requires: host, username, password, uuid, position)

• loxone_set_temperature - Set climate target temperature (requires: host, username, password, uuid, temperature)

• loxone_list_scenes - List available scenes (requires: host, username, password)

• loxone_trigger_scene - Activate a scene (requires: host, username, password, uuid)

• loxone_send_command - Send raw commands (requires: host, username, password, uuid, value)

• loxone_send_secured_command - PIN-protected commands (requires: host, username, password, uuid, value, code)

Example usage:

• "List devices on my Miniserver at 192.168.1.100 with username admin and password mypass"

• "Turn on device uuid abc123 on Miniserver 192.168.1.100 with credentials admin/mypass"

Development

Setup Development Environment

Running Tests and Checks

Testing with Real Miniserver

Testing HTTP Transport

Troubleshooting

Common Issues

Connection Failed

• Check Miniserver IP and credentials

• Verify network connectivity: ping <miniserver-ip>

• Ensure ports 80/443 are accessible

Authentication Failed

• Verify username/password in Loxone Config

• Delete token file and restart: rm loxone_token.json

• Check user permissions in Loxone Config

Device Not Found

• Restart server to reload device structure

• Check device UUID in Loxone Config

• Ensure device is not hidden/disabled

Debug Logging

License

MIT License - see LICENSE file for details.

Related Projects

• Model Context Protocol

• Loxone Smart Home

• Home Assistant Loxone Integration