ipsymcon-mcp-server

MCP-Server für IP-Symcon — lässt Claude/Agenten eine IP-Symcon-Hausautomation nicht nur abfragen und steuern, sondern entwickeln: Objektbaum lesen, PHP-Skripte lesen/ändern/anlegen, Variablen lesen, Geräte schalten. Über die IP-Symcon JSON-RPC-API.

Stack: Python + FastMCP. Companion-Modul für IP-Symcon-seitiges Log-Lesen: SymconMCPBridge (MIT).

Sicherheitsmodell (wichtig)

• Lese-Tools sind immer verfügbar.

• Schreib-/Dev-Tools (ips_set_value, ips_request_action, ips_run_script, ips_set_script_content, ips_create_script, ips_call) brauchen die Umgebungsvariable IPS_ENABLE_WRITE=true. Default ist aus — der bewusste Riegel, damit ein Agent nicht unbemerkt in die laufende Hausautomation schreibt.

• Empfehlung: Schreibzugriff zuerst gegen eine Test-/Staging-Instanz, vorher Backup. (Dry-Run + automatisches Snapshot-Backup vor Änderungen sind als nächster Ausbauschritt geplant.)

Related MCP server: Godot MCP Server

Voraussetzungen in IP-Symcon

1. JSON-RPC-Zugang ist standardmäßig aktiv unter http://<host>:3777/api/.

2. Einen Benutzer mit Zugriff anlegen (Systemsteuerung → Benutzerverwaltung) → in IPS_USER/IPS_PASSWORD eintragen. Hat die Installation keine Authentifizierung, bleiben beide leer.

Installation

cd ~/workspace/ipsymcon-mcp-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env   # dann .env mit echten Werten füllen

Konfiguration (.env)

Start / Test

# direkt starten (stdio)
.venv/bin/python -m ipsymcon_mcp

# mit MCP Inspector testen
.venv/bin/python -m mcp dev ipsymcon_mcp/server.py

Registrierung in Claude Code

claude mcp add ipsymcon -s user -- /Users/<user>/workspace/ipsymcon-mcp-server/.venv/bin/python -m ipsymcon_mcp

(Umgebungsvariablen aus .env werden geladen; alternativ per -e IPS_URL=... etc. übergeben.)

Tools (v0.1)

Lesen (immer verfügbar):

Schreiben/Entwickeln (nur mit IPS_ENABLE_WRITE=true):

Roadmap

• Multi-Instanz-Support — mehrere IP-Symcon-Ziele gleichzeitig ansprechen über benannte Verbindungen (z.B. home = aktuelle Instanz, linux = Migrationsziel). Jedes Tool bekommt einen optionalen instance-Parameter (Default = konfigurierte Standard-Instanz); Config als benannte Map (URL/User/Passwort je Instanz), abwärtskompatibel zum einzelnen IPS_URL. Direkter Treiber: eine IPS-Migration auf Linux — der Agent kann dann aus Alt- und Neu-Instanz lesen, Objekte/Skripte/Events vergleichen und migrieren und das Ergebnis verifizieren, statt blind auf einer Instanz zu arbeiten.

• ips_run_script_capture — Skript via IPS_RunScriptWaitEx ausführen und den return-Wert/Output zurückgeben (heute ist ips_run_script nur fire-and-confirm). Grundlage für agentisches Entwickeln (bauen → ausführen → Ergebnis prüfen → nachbessern) und fürs Log-Lesen.

• ips_read_log — Log-Abruf über das Companion-Modul SymconMCPBridge: ein residenter MessageSink mit gefiltertem Ring-Buffer (KL_ERROR/KL_WARNING/…), der die öffentliche Funktion MCPB_GetLog($id, level, count, filter) per JSON-RPC bereitstellt. ips_read_log ruft dann nur diese Funktion (kein Inline-PHP, kein Logfile-Parsen). Hintergrund: IP-Symcon hat kein direktes „getMessages" (Meldungsfenster = Live-Abo); IPS_GetLogDir() gäbe nur die rohe Logdatei.

• Companion-Modul SymconMCPBridge (MIT, released) — IP-Symcon-seitiges Modul, das Kernel-Log-Meldungen als gefilterten Ring-Buffer über JSON-RPC bereitstellt. Basis für ips_read_log und tiefere Bridge-/Helper-Funktionen. Installation via Module Control (Git-Repo).

• Dedizierte Tools: ips_create_variable, ips_create_event, ips_create_category

• Dry-Run-Modus + automatisches Snapshot-Backup vor Schreibzugriffen

• Objektbaum-Snapshot-Tool (kuratierte Gesamtübersicht)

• Evaluations (mcp-builder Phase 4)

• Gegenstück: Home-Assistant Dev-MCP (zweite Backend-Schicht des Fusionsprojekts)