MCP Server

Plugin McpServer uruchamia serwer Model Context Protocol (MCP) bezpośrednio na Miniserver. Umożliwia asystentom i agentom AI odczytywanie stanu instalacji oraz wysyłanie poleceń do elementów sterujących, korzystając z istniejących pomieszczeń, kategorii i nazw elementów sterujących — bez własnej usługi w chmurze.

Dostęp jest chroniony logowaniem Loxone. Łączący się asystent musi zalogować się za pomocą konta użytkownika Loxone i może widzieć oraz obsługiwać tylko to, na co ten użytkownik ma uprawnienia. Utwórz dedykowanego użytkownika z minimalnymi uprawnieniami potrzebnymi asystentowi.

Spis treści

• Przegląd
• Konfiguracja
• Wymagania wstępne
• Dostęp i uprawnienia
• Co potrafi asystent
• Znajdowanie swojego MCP URL
• Podłączanie asystenta
• Reverse proxy lub domena niestandardowa
• Wejścia, wyjścia, właściwości

Przegląd↑

Model Context Protocol (MCP) to otwarty standard, który umożliwia asystentom AI łączenie się z systemami zewnętrznymi przez dobrze zdefiniowany zestaw narzędzi. Ten plugin implementuje serwer MCP dla Miniserver, dzięki czemu połączony asystent może znajdować elementy sterujące, odczytywać ich bieżący stan i uruchamiać polecenia bez żadnej usługi w chmurze.

Serwer odczytuje strukturę instalacji z Miniserver (pomieszczenia, kategorie, elementy sterujące) i prezentuje ją asystentowi. Żądania asystenta są tłumaczone na te same polecenia sterujące, których używają aplikacje Loxone, dlatego nie jest wymagana dodatkowa konfiguracja poszczególnych elementów sterujących.

Konfiguracja↑

Dodaj plugin McpServer do instalacji i pozwól mu się uruchomić. Asystent łączy się z MCP URL pluginu — dostępny jest jeden adres do dostępu przez internet i jeden dla sieci lokalnej. Zobacz poniżej „Znajdowanie swojego MCP URL”, aby dowiedzieć się, jak je uzyskać, oraz „Podłączanie asystenta”, aby poznać kroki dla popularnych asystentów. Wklej adres odpowiedni dla asystenta; przy pierwszym połączeniu zalogujesz się kontem użytkownika Loxone, aby przyznać dostęp.

Nie jest wymagane konto zewnętrzne ani usługa zewnętrzna. Asystent uwierzytelnia się bezpośrednio na Miniserver, a każde żądanie działa z uprawnieniami zalogowanego użytkownika Loxone.

Wymagania wstępne↑

Wymagany jest Miniserver obsługujący pluginy (.LxAddOn), a także asystent lub agent obsługujący MCP, który może uzyskać dostęp do opublikowanego punktu końcowego, oraz konto użytkownika Loxone, za pomocą którego asystent się zaloguje.

Asystent może widzieć i kontrolować tylko to, na co pozwalają uprawnienia jego użytkownika Loxone. Przyznaj dedykowanemu użytkownikowi minimalne wymagane uprawnienia i w dowolnym momencie cofnij dostęp, wyłączając tego użytkownika lub usuwając połączenie.

Dostęp i uprawnienia↑

Gdy asystent się łączy, działa jako użytkownik Loxone, który się zalogował. Otrzymuje dokładnie uprawnienia tego użytkownika — te same pomieszczenia, kategorie i elementy sterujące, które użytkownik może widzieć i obsługiwać w aplikacjach Loxone, ani więcej, ani mniej.

Utwórz dedykowanego użytkownika Loxone dla każdego asystenta AI i przyznaj mu tylko potrzebne uprawnienia. Asystenci AI mogą błędnie odczytać żądanie lub zadziałać na niewłaściwym elemencie sterującym, a uprawnienia zalogowanego użytkownika są jedynym limitem dostępu egzekwowanym przez sam Miniserver — ograniczony użytkownik utrzymuje ewentualny błąd w bezpiecznych granicach.

Wielu asystentów dodaje drugi limit po stronie klienta: wybierasz, których narzędzi serwera asystent może używać. Narzędzia są oznaczone tagami, aby klient mógł je grupować:

• Read — sprawdzanie struktury i bieżącego stanu (wyszukiwanie elementów sterujących, odczyt wartości, historii, statystyk). Te działania niczego nie zmieniają.

• Write — wysyłanie poleceń, które coś zmieniają, na przykład obsługa elementu sterującego lub ustawienie wartości.

Narzędzia tego serwera służą do odczytu lub zapisu; zezwolenie tylko na narzędzia odczytu pozwala na przykład asystentowi raportować o instalacji bez możliwości zmieniania czegokolwiek. Miejsce ustawienia tego limitu zależy od asystenta — sprawdź jego konektor lub ustawienia MCP.

Co potrafi asystent↑

Serwer pozwala asystentowi pracować z elementami sterującymi, które już istnieją w Twojej instalacji, na dwa sposoby: odczytując ich stan i obsługując je. Korzysta z istniejących pomieszczeń, kategorii i nazw elementów sterujących oraz nie zmienia sposobu zaprogramowania instalacji.

Odczyt stanu, historii i statystyk

Połączony asystent może znajdować elementy sterujące i odczytywać ich bieżące wartości — na przykład czy światło w kuchni jest włączone, jak ciepło jest w pomieszczeniu albo czy drzwi są otwarte. Może również odczytywać zarejestrowaną historię i statystyki, dzięki czemu możesz zadawać pytania takie jak „jaka była wczoraj średnia temperatura w salonie” albo „ile energii zużyła pompa ciepła w zeszłym tygodniu”. Te żądania jedynie odczytują informacje i niczego nie zmieniają.

Wysyłanie poleceń

Asystent może obsługiwać elementy sterujące w taki sam sposób jak aplikacje Loxone: włączać lub wyłączać światło, ściemniać je lub ustawiać kolor, aktywować określony nastrój oświetlenia, podnosić lub obniżać temperaturę zadaną, otwierać lub zamykać żaluzje lub rolety oraz wyzwalać sceny. Każde polecenie działa z uprawnieniami zalogowanego użytkownika Loxone.

Niektóre elementy sterujące są chronione hasłem visu — hasłem na poziomie elementu sterującego, które zabezpiecza pojedynczy element sterujący, oddzielnym od hasła konta używanego do logowania. Asystent nadal może obsługiwać takie elementy sterujące, jeśli podasz to hasło visu; jest ono używane wyłącznie do autoryzacji pojedynczego polecenia i nigdy nie jest przechowywane ani wysyłane do usługi w chmurze.

Czego serwer nie obsługuje

Serwer obsługuje działającą instalację; nie konfiguruje jej ani nie programuje od nowa. Ustawienia wymagające podwyższonych uprawnień — gdzie aplikacja Loxone prosi o ponowne wprowadzenie hasła konta, aby je odblokować — są poza zakresem. Jest to inne hasło niż hasło visu na poziomie elementu sterującego opisane powyżej, a serwer nie może wykonywać tych działań. Należą do nich:

• Zarządzanie użytkownikami — tworzenie lub zmiana użytkowników, praw i uprawnień.

• Tryb Eksperta oraz zmiany konfiguracji wprowadzane w Loxone Config.

• Automatic Designer.

Aby wprowadzić tego typu zmiany, użyj bezpośrednio aplikacji Loxone lub Loxone Config.

Znajdowanie swojego MCP URL↑

Podłączając asystenta, takiego jak Claude, wklejasz adres serwera MCP. Zawsze kończy się on na /mcp. Dostępne są dwa adresy — jeden do połączenia z Miniserver przez internet i jeden w sieci lokalnej. Wybierz ten, który odpowiada sposobowi łączenia się asystenta.

Przez internet — otwórz https://connect.loxonecloud.com/<serial> w przeglądarce, zastępując <serial> numerem seryjnym swojego Miniserver (na przykład https://connect.loxonecloud.com/504F94AABBCC). Przeglądarka przekieruje Cię na własny adres .dyndns.loxonecloud.com Miniserver, który umieszcza publiczny adres IP przekaźnika w nazwie. Skopiuj ten adres dokładnie tak, jak jest pokazany, i dodaj /mcp na końcu.

W sieci lokalnej — przejdź do lokalnego adresu IP Miniserver (na przykład https://192.168.1.50). Nastąpi przekierowanie na jego adres .dyndns.loxonecloud.com, zbudowany w ten sam sposób, ale z lokalnego adresu IP. Skopiuj go i dodaj /mcp na końcu.

Dwa przykłady dla Miniserver o numerze seryjnym 504F94AABBCC — adres publiczny 203.0.113.42, lokalny adres IP 192.168.1.50:

Te adresy są przykładami — skopiuj dokładny host pokazany przez Twoją przeglądarkę po przekierowaniu.

Aby sprawdzić adresy, które plugin faktycznie ogłasza, otwórz jego stronę diagnostyczną: przejdź do https://<your-miniserver>/dev/sps/io/<uuid>/hello, będąc zalogowanym kontem Loxone, gdzie <uuid> to identyfikator obiektu MCP Server w Loxone Config. Strona pokazuje efektywne internetowe i lokalne MCP URLs oraz oznacza każdy z nich jako automatyczny albo jako niestandardowe nadpisanie.

Podłączanie asystenta↑

Poniższe kroki obejmują najpopularniejsze asystenty. W każdym przypadku wklejasz MCP URL z sekcji „Znajdowanie swojego MCP URL” powyżej i logujesz się raz kontem użytkownika Loxone. Użyj adresu internetowego dla asystentów działających w chmurze (takich jak claude.ai) oraz adresu lokalnego dla asystentów działających w tej samej sieci. Przykłady używają adresu internetowego https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp — zastąp go własnym.

Asystenci w chmurze, tacy jak claude.ai — oraz Connectors Claude Desktop — łączą się z chmury asystenta i docierają do serwera tylko przez standardowy HTTPS na porcie 443. Remote Connect publikuje Miniserver na niestandardowym porcie, więc adres Remote Connect nie działa dla tych połączeń w chmurze; udostępnij punkt końcowy na porcie 443 za pomocą reverse proxy lub domeny niestandardowej opisanej poniżej w sekcji „Reverse proxy lub domena niestandardowa”. Asystenci, którzy uruchamiają lokalny most na Twoim komputerze — Local MCP Server Claude Desktop, Claude Code, LM Studio — mogą używać adresu Remote Connect bezpośrednio, na dowolnym porcie. Asystenci w Twojej sieci mogą używać adresu lokalnego, dzięki czemu ruch pozostaje w LAN.

Claude (claude.ai, w przeglądarce)

Otwórz Ustawienia (Settings) i przejdź do Connectors. Wybierz dodanie niestandardowego konektora, nadaj mu nazwę, na przykład Loxone, i wklej internetowy MCP URL kończący się na /mcp. Zapisz go, następnie otwórz konektor i zaloguj się kontem Loxone, aby autoryzować dostęp. Connector działa z chmury Claude i działa tylko wtedy, gdy Twój adres internetowy jest osiągalny przez standardowy HTTPS (port 443). Adres Remote Connect używa niestandardowego portu i nie połączy się w ten sposób — udostępnij punkt końcowy na porcie 443 za pomocą reverse proxy lub domeny niestandardowej opisanej poniżej. aktualne kroki Anthropic

Claude Desktop

Claude Desktop oferuje dwa sposoby dodania serwera i tutaj zachowują się one inaczej. Jego ustawienie Connectors przekazuje URL do chmury Claude — tą samą ścieżką co claude.ai w przeglądarce — dlatego działa tylko na standardowym HTTPS (port 443), a nie z adresem Remote Connect na niestandardowym porcie. Zamiast tego dodaj Local MCP Server: w Ustawienia (Settings) → Developer uruchamia on mały most na Twoim komputerze, który może dotrzeć do Miniserver na dowolnym porcie, w tym do adresu Remote Connect. Wybierz Edit Config i dodaj serwer do claude_desktop_config.json (aktualne kroki Anthropic):

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

Uruchom ponownie Claude Desktop; otworzy się okno przeglądarki do logowania Loxone.

Claude Code (wiersz poleceń)

Dodaj serwer za pomocą CLI Claude Code:

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

Następnie uruchom /mcp w Claude Code i dokończ logowanie Loxone w przeglądarce.

LM Studio

Otwórz kartę Program i wybierz Edit mcp.json, następnie dodaj serwer w sekcji mcpServers z polem url:

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

Zapisz plik; LM Studio poprosi Cię o zalogowanie się kontem Loxone.

Reverse proxy lub domena niestandardowa↑

Większość instalacji nie wymaga tu żadnych ustawień — domyślnie plugin sam ustala i ogłasza swoje adresy. Reverse proxy lub domena niestandardowa są potrzebne głównie dla asystentów w chmurze: klienci tacy jak claude.ai (oraz Connectors Claude Desktop) łączą się przez standardowy HTTPS na porcie 443 z publicznie zaufanym certyfikatem, a Remote Connect publikuje Miniserver na niestandardowym porcie, więc adres Remote Connect nie może być dla nich używany. Umieszczenie Miniserver za reverse proxy lub domeną niestandardową, która udostępnia punkt końcowy na porcie 443 (na przykład tunel Cloudflare lub nginx), sprawia, że staje się osiągalny — jest to także właściwa droga, jeśli po prostu chcesz używać własnej domeny i certyfikatu.

Gdy używasz takiego rozwiązania, wskaż pluginowi, który adres publiczny ma ogłaszać. W przeciwnym razie adres automatyczny wskazuje na Miniserver za proxy zamiast na samo proxy, a logowanie się nie powiedzie.

To, które pole wypełnisz, zależy od tego, jak proxy łączy się z Miniserver — nie od tego, gdzie działa asystent:

• Niestandardowy zewnętrzny adres URL — ustaw to, gdy proxy łączy się z Miniserver przez jego adres zewnętrzny (publiczny adres IP albo Remote Connect).

• Niestandardowy lokalny adres URL — ustaw to, gdy proxy łączy się z Miniserver przez jego adres lokalny w LAN.

Wprowadzana wartość to własny publiczny MCP URL proxy — adres wklejany przez asystentów — na przykład https://mcp.example.com/mcp. Akceptowane są tylko adresy https. Pozostaw pole puste, aby zachować adres automatyczny dla tej ścieżki; ustaw jedno, drugie albo oba pola.

Proxy musi przekazywać cały host, nie tylko /mcp. Zarówno ścieżki /mcp, jak i ścieżki /.well-known na poziomie głównym muszą docierać do Miniserver. Logowanie używa adresu wykrywania w katalogu głównym hosta (https://mcp.example.com/.well-known/oauth-authorization-server/mcp), który znajduje się poza /mcp. Proxy przekazujące tylko /mcp pozwala asystentowi znaleźć serwer, ale nie usługę logowania, dlatego połączenie się nie powiedzie.

Wejścia diagnostyczne↑

Właściwości↑