MCP Server

Das McpServer-Plugin betreibt einen Model Context Protocol (MCP)-Server direkt auf dem Miniserver. Damit können KI-Assistenten und Agenten den Zustand Ihrer Installation abfragen und Befehle an Steuerungen senden. Dabei werden Ihre vorhandenen Räume, Kategorien und Steuerungsnamen verwendet — ohne eigenen Cloud-Dienst.

Der Zugriff ist durch den Loxone Login geschützt. Ein verbindender Assistent muss sich mit einem Loxone Benutzerkonto anmelden und kann nur sehen und bedienen, wozu dieser Benutzer berechtigt ist. Erstellen Sie einen eigenen Benutzer mit den minimalen Rechten, die der Assistent benötigt.

Inhaltsverzeichnis

• Übersicht
• Einrichtung
• Voraussetzungen
• Zugriff und Berechtigungen
• Was ein KI Assistent kann
• Ihre MCP URL finden
• Assistenten verbinden
• Reverse-Proxy oder benutzerdefinierte Domain
• Eingänge, Ausgänge, Eigenschaften

Übersicht↑

Model Context Protocol (MCP) ist ein offener Standard, mit dem KI-Assistenten über klar definierte Werkzeuge eine Verbindung zu externen Systemen herstellen können. Dieses Plugin implementiert einen MCP-Server für den Miniserver, sodass ein verbundener Assistent Steuerungen finden, deren aktuellen Zustand lesen und Befehle auslösen kann, ohne einen Cloud-Dienst zu verwenden.

Der Server liest die Installationsstruktur vom Miniserver (Räume, Kategorien, Steuerungen) und stellt sie dem Assistenten bereit. Anfragen des Assistenten werden in dieselben Steuerbefehle übersetzt, die auch die Loxone Apps verwenden. Daher ist keine zusätzliche Konfiguration einzelner Steuerungen erforderlich.

Einrichtung↑

Fügen Sie das McpServer-Plugin zur Installation hinzu und lassen Sie es starten. Ihr Assistent verbindet sich mit der MCP URL des Plugins — es gibt eine Adresse für den Zugriff über das Internet und eine für das lokale Netzwerk. Unter „Ihre MCP URL finden“ erfahren Sie, wie Sie diese Adressen erhalten; unter „Assistenten verbinden“ finden Sie die Schritte für gängige Assistenten. Fügen Sie die Adresse ein, die zu Ihrem Assistenten passt. Beim ersten Verbindungsaufbau melden Sie sich mit einem Loxone Benutzerkonto an, um Zugriff zu gewähren.

Es ist kein Drittanbieter-Konto und kein externer Dienst erforderlich. Der Assistent authentifiziert sich direkt am Miniserver, und jede Anfrage wird mit den Berechtigungen des angemeldeten Loxone Benutzers ausgeführt.

Voraussetzungen↑

Erforderlich ist ein Miniserver, der Plugins (.LxAddOn) unterstützt, sowie ein MCP-fähiger Assistent oder Agent, der den veröffentlichten Endpunkt erreichen kann, und ein Loxone Benutzerkonto, mit dem sich der Assistent anmeldet.

Ein Assistent kann nur sehen und steuern, wozu sein Loxone Benutzer berechtigt ist. Geben Sie dem eigenen Benutzer nur die mindestens erforderlichen Rechte und entziehen Sie den Zugriff jederzeit, indem Sie diesen Benutzer deaktivieren oder die Verbindung entfernen.

Zugriff und Berechtigungen↑

Wenn ein Assistent eine Verbindung herstellt, handelt er als der Loxone Benutzer, der sich anmeldet. Er erhält exakt die Rechte dieses Benutzers — dieselben Räume, Kategorien und Steuerungen, die dieser Benutzer in den Loxone Apps sehen und bedienen kann, nicht mehr und nicht weniger.

Erstellen Sie für jeden KI-Assistenten einen eigenen Loxone Benutzer und geben Sie ihm nur die Rechte, die er benötigt. KI-Assistenten können eine Anfrage falsch verstehen oder die falsche Steuerung bedienen, und die Berechtigungen des angemeldeten Benutzers sind die einzige Zugriffsbeschränkung, die der Miniserver selbst erzwingt — ein eingeschränkter Benutzer hält jeden Fehler in sicheren Grenzen.

Viele Assistenten fügen eine zweite, clientseitige Einschränkung hinzu: Sie wählen, welche Werkzeuge des Servers der Assistent verwenden darf. Werkzeuge sind markiert, damit ein Client sie gruppieren kann:

• Read — Struktur und aktuellen Zustand abrufen (Steuerungen finden, Werte lesen, Historie, Statistiken). Diese ändern nichts.

• Write — Befehle senden, die etwas ändern, zum Beispiel eine Steuerung bedienen oder einen Wert setzen.

Die Werkzeuge dieses Servers sind lesend oder schreibend; wenn Sie zum Beispiel nur lesende Werkzeuge erlauben, kann ein Assistent über die Installation berichten, ohne etwas ändern zu können. Wo Sie diese Einschränkung festlegen, hängt vom Assistenten ab — siehe dessen Connector- oder MCP Einstellungen.

Was ein KI Assistent kann↑

Der MCP Server ermöglicht es einem KI Assistenten, mit den bereits in Ihrer Installation vorhandenen Bausteinen auf zwei Arten zu arbeiten: ihren Zustand auszulesen und sie zu bedienen. Dabei werden Ihre bestehenden Räume, Kategorien und Bausteinnamen verwendet, und es wird nicht verändert, wie die Installation programmiert ist.

Zustand, Verlauf und Statistiken auslesen

Ein verbundener Assistent kann Bausteine finden und ihre aktuellen Werte auslesen — zum Beispiel, ob das Licht in der Küche eingeschaltet ist, wie warm es in einem Raum ist oder ob eine Tür geöffnet ist. Er kann außerdem aufgezeichnete Verläufe und Statistiken auslesen, sodass Sie Fragen stellen können wie „Wie hoch war gestern die durchschnittliche Temperatur im Wohnzimmer" oder „Wie viel Energie hat die Wärmepumpe letzte Woche verbraucht". Diese Anfragen lesen ausschließlich Informationen aus und verändern nichts.

Befehle senden

Der Assistent kann Bausteine auf dieselbe Weise bedienen wie die Loxone Apps: ein Licht ein- oder ausschalten, dimmen oder eine Farbe einstellen, eine bestimmte Lichtstimmung aktivieren, eine Solltemperatur erhöhen oder senken, Jalousien oder Beschattungen verfahren und Szenen auslösen. Jeder Befehl wird mit den Berechtigungen des angemeldeten Loxone Benutzers ausgeführt.

Manche Bausteine sind durch ein Visualisierungs Passwort geschützt — ein Passwort auf Baustein-Ebene, das einen einzelnen Baustein absichert und das vom Konto-Passwort für die Anmeldung getrennt ist. Ein Assistent kann solche Bausteine dennoch bedienen, wenn Sie dieses Visu-Passwort angeben; es wird ausschließlich zur Autorisierung des einzelnen Befehls verwendet und niemals gespeichert oder an einen Cloud-Dienst gesendet.

Was nicht unterstützt wird

Der Server bedient eine laufende Installation; er konfiguriert oder programmiert sie nicht neu. Einstellungen, die erweiterte Rechte erfordern — bei denen die Loxone App Sie auffordert, Ihr Konto-Passwort erneut einzugeben, um sie freizuschalten — werden nicht unterstützt. Dabei handelt es sich um ein anderes Passwort als das oben genannte Visu-Passwort auf Baustein-Ebene, und der Server kann diese Aktionen nicht ausführen. Dazu gehören:

• Benutzerverwaltung — das Anlegen oder Ändern von Benutzern, Rechten und Berechtigungen.

• Der Expertenmodus und Konfigurationsänderungen, die in Loxone Config vorgenommen werden.

• Der Automatik-Designer.

Um solche Änderungen vorzunehmen, verwenden Sie direkt die Loxone App oder Loxone Config.

Ihre MCP URL finden↑

Wenn Sie einen Assistenten wie Claude verbinden, fügen Sie die Adresse des MCP-Server ein. Sie endet immer auf /mcp. Es gibt zwei Adressen — eine, um den Miniserver über das Internet zu erreichen, und eine in Ihrem lokalen Netzwerk. Wählen Sie die Adresse, die zur Verbindungsart Ihres Assistenten passt.

Über das Internet — öffnen Sie https://connect.loxonecloud.com/<serial> in einem Browser und ersetzen Sie <serial> durch die Seriennummer Ihres Miniserver (zum Beispiel https://connect.loxonecloud.com/504F94AABBCC). Ihr Browser wird zur eigenen .dyndns.loxonecloud.com-Adresse des Miniserver weitergeleitet, die die öffentliche Relay-IP in den Namen einbaut. Kopieren Sie diese Adresse genau wie angezeigt und fügen Sie am Ende /mcp hinzu.

Im lokalen Netzwerk — rufen Sie die lokale IP-Adresse des Miniserver auf (zum Beispiel https://192.168.1.50). Sie werden auf dessen .dyndns.loxonecloud.com-Adresse weitergeleitet, die auf dieselbe Weise, aber aus der lokalen IP, gebildet wird. Kopieren Sie sie und fügen Sie am Ende /mcp hinzu.

Zwei durchgerechnete Beispiele für einen Miniserver mit der Seriennummer 504F94AABBCC — öffentliche Adresse 203.0.113.42, lokale IP 192.168.1.50:

Diese Adressen sind Beispiele — kopieren Sie den exakten Host, den Ihr eigener Browser nach der Weiterleitung anzeigt.

Um zu prüfen, welche Adressen das Plugin tatsächlich veröffentlicht, öffnen Sie seine Diagnoseseite: Rufen Sie https://<your-miniserver>/dev/sps/io/<uuid>/hello auf, während Sie mit einem Loxone Konto angemeldet sind. Dabei ist <uuid> die Kennung des MCP Server Objekts in Loxone Config. Dort werden die wirksamen Internet- und lokalen MCP URLs aufgelistet und jeweils als automatisch oder als benutzerdefinierte Überschreibung markiert.

Assistenten verbinden↑

Die folgenden Schritte decken die gängigsten Assistenten ab. In jedem Fall fügen Sie die MCP URL aus „Ihre MCP URL finden“ oben ein und melden sich einmal mit einem Loxone Benutzerkonto an. Verwenden Sie die Internetadresse für Assistenten, die in der Cloud laufen (z. B. claude.ai), und die lokale Adresse für Assistenten im selben Netzwerk. Die Beispiele verwenden die Internetadresse https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp — ersetzen Sie sie durch Ihre eigene.

Cloud-Assistenten wie claude.ai — und die Connectors von Claude Desktop — verbinden sich aus der Cloud des Assistenten und erreichen den Server nur über Standard-HTTPS auf Port 443. Remote Connect veröffentlicht den Miniserver auf einem nicht standardmäßigen Port, daher funktioniert eine Remote Connect Adresse für diese Cloud-Verbindungen nicht; stellen Sie den Endpunkt auf Port 443 mit dem unten unter „Reverse-Proxy oder benutzerdefinierte Domain“ beschriebenen Reverse-Proxy oder der benutzerdefinierten Domain bereit. Assistenten, die eine lokale Bridge auf Ihrem eigenen Computer ausführen — der Local MCP Server von Claude Desktop, Claude Code, LM Studio — können eine Remote Connect Adresse direkt auf jedem Port verwenden. Assistenten in Ihrem eigenen Netzwerk können die lokale Adresse verwenden; dadurch bleibt der Datenverkehr im LAN.

Claude (claude.ai, im Browser)

Öffnen Sie Einstellungen (Settings) und wechseln Sie zu Connectors. Wählen Sie das Hinzufügen eines benutzerdefinierten Connectors, geben Sie ihm einen Namen wie Loxone und fügen Sie Ihre MCP URL für das Internet ein, die auf /mcp endet. Speichern Sie ihn, öffnen Sie anschließend den Connector und melden Sie sich mit Ihrem Loxone Konto an, um den Zugriff zu autorisieren. Ein Connector läuft aus der Cloud von Claude und funktioniert nur, wenn Ihre Internetadresse über Standard-HTTPS (Port 443) erreichbar ist. Eine Remote Connect Adresse verwendet einen nicht standardmäßigen Port und stellt auf diese Weise keine Verbindung her — stellen Sie den Endpunkt auf Port 443 mit dem unten beschriebenen Reverse-Proxy oder der benutzerdefinierten Domain bereit. aktuelle Schritte von Anthropic

Claude Desktop

Claude Desktop bietet zwei Möglichkeiten, einen Server hinzuzufügen, und sie verhalten sich hier unterschiedlich. Die Connectors Einstellung übergibt die URL an die Cloud von Claude — derselbe Pfad wie claude.ai im Browser — und funktioniert daher nur mit Standard-HTTPS (Port 443) und nicht mit einer Remote Connect Adresse auf einem nicht standardmäßigen Port. Fügen Sie stattdessen einen Local MCP Server hinzu: Unter Einstellungen (Settings) → Developer führt er eine kleine Bridge auf Ihrem eigenen Computer aus, die den Miniserver auf jedem Port erreichen kann, einschließlich einer Remote Connect Adresse. Wählen Sie Edit Config und fügen Sie den Server zu claude_desktop_config.json hinzu (aktuelle Schritte von Anthropic):

{ "mcpServers": { "loxone": { "command": "npx", "args": ["mcp-remote", "https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp"] } } }

Starten Sie Claude Desktop neu; für die Loxone Anmeldung öffnet sich ein Browserfenster.

Claude Code (Befehlszeile)

Fügen Sie den Server mit der Claude Code CLI hinzu:

claude mcp add --transport http loxone https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp

Führen Sie anschließend /mcp in Claude Code aus und schließen Sie die Loxone Anmeldung in Ihrem Browser ab.

LM Studio

Öffnen Sie den Program Tab und wählen Sie Edit mcp.json. Fügen Sie den Server dann unter mcpServers mit einem url-Feld hinzu:

{ "mcpServers": { "loxone": { "url": "https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp" } } }

Speichern Sie die Datei; LM Studio fordert Sie auf, sich mit Ihrem Loxone Konto anzumelden.

Reverse-Proxy oder benutzerdefinierte Domain↑

Die meisten Installationen benötigen hier nichts — standardmäßig ermittelt und veröffentlicht das Plugin seine eigenen Adressen. Ein Reverse-Proxy oder eine benutzerdefinierte Domain wird vor allem für Cloud-Assistenten benötigt: Clients wie claude.ai (und die Connectors von Claude Desktop) verbinden sich über Standard-HTTPS auf Port 443 mit einem öffentlich vertrauenswürdigen Zertifikat, während Remote Connect den Miniserver auf einem nicht standardmäßigen Port veröffentlicht. Daher kann eine Remote Connect Adresse für sie nicht verwendet werden. Wenn der Miniserver hinter einem Reverse-Proxy oder einer benutzerdefinierten Domain steht, die den Endpunkt auf Port 443 bereitstellt (zum Beispiel ein Cloudflare Tunnel oder nginx), wird er erreichbar — dies ist auch der Weg, wenn Sie einfach Ihre eigene Domain und Ihr eigenes Zertifikat verwenden möchten.

Wenn Sie einen verwenden, teilen Sie dem Plugin mit, welche öffentliche Adresse es veröffentlichen soll. Andernfalls zeigt die automatische Adresse auf den Miniserver hinter dem Proxy statt auf den Proxy selbst, und die Anmeldung schlägt fehl.

Welches Feld Sie ausfüllen, hängt davon ab, wie Ihr Proxy den Miniserver erreicht — nicht davon, wo der Assistent läuft:

• Benutzerdefinierte externe URL — setzen Sie dies, wenn Ihr Proxy den Miniserver über dessen externe Adresse erreicht (öffentliche IP oder Remote Connect).

• Benutzerdefinierte lokale URL — setzen Sie dies, wenn Ihr Proxy den Miniserver über dessen lokale Adresse im LAN erreicht.

Der eingegebene Wert ist die eigene öffentliche MCP URL des Proxys — die Adresse, die Assistenten einfügen — zum Beispiel https://mcp.example.com/mcp. Es werden nur https-Adressen akzeptiert. Lassen Sie ein Feld leer, um die automatische Adresse für diesen Pfad beizubehalten; setzen Sie ein Feld, das andere oder beide.

Der Proxy muss den gesamten Host weiterleiten, nicht nur /mcp. Sowohl die /mcp Pfade als auch die /.well-known Pfade auf Root-Ebene müssen den Miniserver erreichen. Die Anmeldung verwendet eine Discovery-Adresse an der Wurzel des Hosts (https://mcp.example.com/.well-known/oauth-authorization-server/mcp), die außerhalb von /mcp liegt. Ein Proxy, der nur /mcp weiterleitet, lässt den Assistenten zwar den Server finden, aber nicht den Login-Dienst. Dadurch schlägt die Verbindung fehl.

Diagnose-Eingänge↑

Eigenschaften↑