Ips Automation

Ein Model Context Protocol (MCP) Server, der Claude (oder andere MCP-Clients) direkten Zugriff auf die JSON-RPC API von IP-Symcon gibt. Damit kann Claude deine PHP-Skripte lesen, analysieren, optimieren, neu erstellen und ausführen – die Automatisierungs-Entwicklung wird dadurch zum Dialog.

⚠️ Dieser Server greift direkt über die native JSON-RPC API (Port 3777) auf IP-Symcon zu. Es muss kein zusätzliches PHP-Modul in IP-Symcon installiert werden – nur der Fernzugriff muss aktiviert sein.

---

Was kann der Server?

Claude bekommt 13 Tools, mit denen es eigenständig in deinem IPS-System arbeiten kann:

Skript-Tools (Kernfunktion)

Tool	Beschreibung
script_list	Alle Skripte auflisten (Name, ID, Status, letzter Lauf), optional mit Suchfilter
script_read	PHP-Quellcode eines Skripts lesen + Metadaten
script_write	Code überschreiben (mit Typ-Prüfung als Sicherheitsnetz)
script_create	Neues Skript anlegen + Code setzen (mit Rollback bei Fehler)
script_execute	Skript ausführen + Ergebnis/Laufzeit zurückgeben
script_delete	Skript löschen
php_eval	PHP-Code direkt testen (über temporäres Skript, wird automatisch aufgeräumt)
cleanup_eval_scripts	Verwaiste Temp-Skripte aufräumen (mit Vorschau-Modus)

Kontext-Tools

Tool	Beschreibung
object_search	Objekte/Variablen nach Name suchen → liefert IDs für neue Skripte
variable_read	Variable lesen (Wert + Metadaten)
variable_set	Variable setzen / Aktion auslösen (RequestAction oder SetValue)
object_children	Objektbaum navigieren

System-Tools

Tool	Beschreibung
system_info	IPS Version + Laufzeit
system_log	Fehlerlog lesen – ideal zur Diagnose nach einem Skript-Fehler

---

Architektur

┌─────────────────┐   stdio    ┌──────────────────┐   JSON-RPC    ┌──────────────┐
│  Claude Desktop │ ─────────► │  MCP Server      │ ────────────► │  IP-Symcon   │
│  (dein PC)      │            │  (Node.js)       │   Port 3777   │              │
└─────────────────┘            └──────────────────┘               └──────────────┘

Der MCP-Server läuft auf demselben PC wie Claude Desktop und verbindet sich übers Netzwerk mit IP-Symcon. Geschrieben in TypeScript mit dem offiziellen @modelcontextprotocol/sdk.

---

Voraussetzungen

• Node.js 18+ (nodejs.org, LTS-Version)
• IP-Symcon mit aktiviertem Fernzugriff
• Claude Desktop (oder ein anderer MCP-Client)

---

Installation

1. Fernzugriff in IP-Symcon aktivieren

Die JSON-RPC API ist durch den Fernzugriff abgesichert.

1. IP-Symcon Verwaltungskonsole öffnen
2. Einstellungen → Fernzugriff
3. Ein Passwort vergeben und speichern

Notiere dir drei Werte:

• Host/IP deines IP-Symcon Servers (z.B. 192.168.1.100)
• Benutzer = deine Lizenz-E-Mail-Adresse (nicht der Account-Name!)
• Passwort = das eben gesetzte Fernzugriff-Passwort

2. Repository klonen & bauen

git clone https://github.com/badfrog18/ips-automation-mcp.git
cd ips-automation-mcp
npm install
npm run build

Windows / PowerShell: Falls npm install mit einem Fehler "die Ausführung von Skripts ist deaktiviert" abbricht, nutze stattdessen npm.cmd install und npm.cmd run build – oder gib einmalig die Execution Policy frei: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

3. Verbindung testen (empfohlen)

Bevor du Claude konfigurierst, prüfe ob die Verbindung steht:

Windows (CMD):

set IPS_HOST=192.168.1.100 && set [email protected] && set IPS_PASS=deinPasswort && node test-connection.mjs

Windows (PowerShell):

$env:IPS_HOST="192.168.1.100"; $env:IPS_USER="[email protected]"; $env:IPS_PASS="deinPasswort"; node test-connection.mjs

macOS/Linux:

IPS_HOST=192.168.1.100 [email protected] IPS_PASS=deinPasswort node test-connection.mjs

Bei Erfolg zeigt das Skript deine IP-Symcon-Version und die Anzahl deiner Skripte/Objekte.

4. Claude Desktop konfigurieren

Öffne in Claude Desktop: Einstellungen → Entwickler → Konfiguration bearbeiten. Das öffnet (bzw. erstellt) die Datei claude_desktop_config.json.

Füge den mcpServers-Block hinzu (Pfad und Zugangsdaten anpassen):

{
  "mcpServers": {
    "ips-automation": {
      "command": "node",
      "args": ["C:/Tools/ips-automation-mcp/dist/server.js"],
      "env": {
        "IPS_HOST": "192.168.1.100",
        "IPS_PORT": "3777",
        "IPS_USER": "[email protected]",
        "IPS_PASS": "deinPasswort"
      }
    }
  }
}

Windows-Pfade: Im JSON entweder Schrägstriche / oder doppelte Backslashes \\ verwenden – einfache Backslashes brechen die Datei.

Bestehende Config: Falls schon andere MCP-Server eingetragen sind, füge nur den "ips-automation"-Block innerhalb von "mcpServers" hinzu, statt die Datei zu ersetzen.

5. Claude Desktop neu starten

Komplett beenden (Windows: Rechtsklick aufs Tray-Icon → Beenden) und neu öffnen. Ein einfaches Schließen des Fensters reicht nicht.

6. Testen

Frag Claude:

„Zeige mir alle meine IP-Symcon Skripte"

Claude ruft dann script_list auf und listet deine Skripte.

---

Umgebungsvariablen

Variable	Standard	Beschreibung
IPS_HOST	127.0.0.1	IP-Symcon Hostname/IP
IPS_PORT	3777	JSON-RPC Port
IPS_USER	–	Lizenz-E-Mail (Pflicht)
IPS_PASS	–	Fernzugriff-Passwort (Pflicht)
IPS_HTTPS	false	HTTPS statt HTTP
IPS_TIMEOUT	30000	Timeout pro Anfrage in ms – auf langsamen/großen Systemen (Raspi, große DB) höher setzen

---

Beispiel-Workflows

"Zeig alle Skripte mit 'Pool' im Namen"
 → script_list (gefiltert)

"Lies das Poolpumpen-Skript und erkläre, was es macht"
 → script_read + Analyse

"Optimiere das Skript und schreib die verbesserte Version zurück"
 → script_read → script_write

"Erstelle eine Automation, die bei PV-Überschuss die Poolpumpe einschaltet"
 → object_search (IDs finden) → script_create → script_execute

"Das Skript wirft einen Fehler – finde und behebe ihn"
 → script_execute → system_log → script_write

---

Sicherheitshinweis

Der Server hat vollen Lese- und Schreibzugriff (inkl. Löschen und Ausführen) auf deine IPS-Skripte. Die claude_desktop_config.json enthält dein Fernzugriff-Passwort im Klartext – behandle sie entsprechend vertraulich und committe sie niemals in ein öffentliches Repo (sie ist in der .gitignore ausgeschlossen).

---

Changelog

v2.2.0

• Performance: object_search, script_list und object_children laufen jetzt vollständig serverseitig in IP-Symcon (ein einziger RPC-Call statt tausender Einzelanfragen). Damit funktionieren sie auch auf großen Systemen (>10.000 Objekte) zuverlässig, ohne Timeout. Behebt „Failed to call tool object_search" / „MCP-Server reagiert nicht".
• Konfigurierbarer Timeout über IPS_TIMEOUT (Standard jetzt 30s statt 15s) – für langsame Hosts wie Raspberry Pi
• Interne evalPhp-Hilfsfunktion für zuverlässige serverseitige Ausführung mit echtem JSON-Rückgabewert

v2.1.0

• Fix: Temporäre php_eval-Skripte werden jetzt zuverlässig gelöscht (inkl. PHP-Datei auf der Platte). Ursache war der fehlende zweite Parameter delete_file bei IPS_DeleteScript.
• Automatisches Aufräumen verwaister __claude_eval_-Skripte beim Serverstart
• Neues Tool cleanup_eval_scripts (mit Vorschau-Modus) zum manuellen Aufräumen
• script_delete nutzt jetzt ebenfalls robustes Löschen + Typprüfung

v2.0.0

• Erste Veröffentlichung mit 13 Tools für Skript-Automatisierung

---

Lizenz

MIT – siehe LICENSE.

Haftungsausschluss

Dieses Projekt steht in keiner Verbindung zur Symcon GmbH.

Die Nutzung erfolgt vollständig auf eigene Gefahr und eigene Verantwortung. Der Autor übernimmt keinerlei Haftung für direkte oder indirekte Schäden, Datenverluste, Fehlfunktionen, Ausfälle oder sonstige Folgen, die aus der Installation, Konfiguration oder Nutzung dieser Software entstehen – gleich aus welchem Rechtsgrund.

Zu beachten ist insbesondere, dass Claude eigenständig Skripte ändern, ausführen und löschen kann. Vor dem produktiven Einsatz wird dringend ein vollständiges Backup des IP-Symcon Systems empfohlen. Jeder Nutzer ist selbst dafür verantwortlich, Änderungen vor dem Übernehmen zu prüfen.

Die Software wird „wie besehen" („as is") ohne jegliche Gewährleistung bereitgestellt, wie in der MIT-Lizenz ausgeführt.