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)
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Install and run the server
# Clone and setup
git clone <repository-url>
cd loxone-mcp-server
# Install dependencies
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
# Run the server (no configuration needed)
uv run loxone-mcp-server
Configuration
The server is stateless and does not require environment credentials. Each MCP client provides credentials when calling tools.
Optional server configuration:
# Optional server settings
MCP_TRANSPORT=http # Set to 'http' for HTTP mode (default: 'stdio')
MCP_HOST=127.0.0.1 # HTTP host (default: '127.0.0.1')
MCP_PORT=8000 # HTTP port (default: 8000)
LOG_LEVEL=INFO # Logging level
Running the MCP Server
The server supports two transport modes:
1. Stdio Mode (Default)
For MCP clients like Claude Desktop that connect via stdio:
# Run with stdio transport (default)
uv run loxone-mcp-server
2. HTTP Mode
For web-based clients or Amazon Q CLI that connect via HTTP:
# Run with HTTP transport
MCP_TRANSPORT=http uv run loxone-mcp-server
# Or use the dedicated HTTP command
uv run loxone-mcp-server-http
# Server will be available at: http://127.0.0.1:8000/mcp
Amazon Q CLI MCP Configuration
Setup Amazon Q CLI Agent (Stdio Mode)
The project includes a pre-configured Amazon Q CLI agent:
# Activate the agent (no credentials needed - provided per tool call)
q use agent loxone-smart-home
The agent configuration is in .amazonq/cli-agents/loxone-agent.json and includes:
- MCP server setup with
uvrunner - 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:
# Start HTTP server (no credentials needed)
MCP_TRANSPORT=http uv run loxone-mcp-server
# Server will show: "MCP endpoint will be available at: http://127.0.0.1:8000/mcp"
Console 2 - Configure Amazon Q CLI:
# Create HTTP-based agent configuration
q agent create loxone-http --mcp-server http://127.0.0.1:8000/mcp
# Or modify existing agent to use HTTP endpoint
q settings set agent.loxone-smart-home.mcp_endpoint http://127.0.0.1:8000/mcp
# Use the agent
q use agent loxone-http
Using with Other MCP Clients
Claude Desktop (Stdio Mode)
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"loxone": {
"command": "uv",
"args": ["--directory", "/path/to/loxone-mcp-server", "run", "loxone-mcp-server"]
}
}
}
Claude Desktop (HTTP Mode)
For HTTP mode, start the server separately and configure Claude Desktop to connect via HTTP:
- Start the server in HTTP mode:
MCP_TRANSPORT=http uv run loxone-mcp-server
- Configure Claude Desktop for HTTP:
{
"mcpServers": {
"loxone": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
Other MCP Clients
- Stdio mode: Use the command-line pattern shown above
- HTTP mode: Connect to
http://127.0.0.1:8000/mcpendpoint
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
# Install dependencies
uv pip install -e ".[dev]"
# Setup pre-commit hooks (optional but recommended)
make setup-pre-commit
Running Tests and Checks
# Run all CI checks locally
make ci-check
# Individual commands
make test # Run tests with coverage
make lint # Check code with ruff
make format # Format code with black
make type-check # Type check with mypy
Testing with Real Miniserver
# Integration tests now use credentials passed to tools
uv run pytest tests/integration/
Testing HTTP Transport
# Start server in HTTP mode (no credentials needed)
MCP_TRANSPORT=http uv run loxone-mcp-server
# In another terminal, test the endpoint
curl -X POST http://127.0.0.1:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'
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
export LOG_LEVEL=DEBUG
uv run loxone-mcp-server
License
MIT License - see LICENSE file for details.