IPS Automation MCP Server

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)

Kontext-Tools

System-Tools

Related MCP server: Homey MCP Server

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 IPS_USER=deine@email.de && set IPS_PASS=deinPasswort && node test-connection.mjs

Windows (PowerShell):

$env:IPS_HOST="192.168.1.100"; $env:IPS_USER="deine@email.de"; $env:IPS_PASS="deinPasswort"; node test-connection.mjs

macOS/Linux:

IPS_HOST=192.168.1.100 IPS_USER=deine@email.de 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": "deine@email.de",
        "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

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.