MCP-Server — KI-Zugriff für OpenSprinkler

Die OpenSprinkler-MCP-Integration (Model Context Protocol) ermöglicht KI-Assistenten, einen OpenSprinkler-Controller über dokumentierte Tools abzufragen und zu steuern.

Diese Seite behandelt nur MCP-Einrichtung und Betriebsarten. Programmerstellung und Sensor-Automation sind ausgelagert:

Betriebsarten

Eingebauter Firmware-MCP

Der eingebaute MCP-Server läuft direkt in ESP32-Firmware-Builds mit aktiviertem USE_OTF:

POST http://<controller-ip>/mcp
Content-Type: application/json

Die Authentifizierung nutzt denselben Admin-Passwort-Hash wie die REST-API: ?pw=, Header X-OS-Password oder Bearer Token.

Plattform: nur ESP32 / ESP32-C5 mit USE_OTF; nicht ESP8266 und nicht OSPi.

Externer Node.js-MCP-Server

Der externe Server unter tools/mcp-server/ läuft außerhalb der Firmware und stellt die REST-API über stdio bereit. Er funktioniert mit ESP8266-, ESP32- und OSPi-Controllern und bietet einen größeren Tool-Satz inklusive Sensoren, Monitoren, Zigbee, BLE und Systemressourcen, sofern der Zielcontroller diese unterstützt.

Einrichtung

Voraussetzungen

Node.js 18 oder neuer.
Ein erreichbarer OpenSprinkler-Controller.
Das Admin-Passwort als MD5-Hash.

Installation und Build

cd tools/mcp-server
npm install
npm run build

VS Code / GitHub Copilot

In .vscode/mcp.json eintragen:

{
  "servers": {
    "opensprinkler": {
      "type": "stdio",
      "command": "node",
      "args": ["tools/mcp-server/dist/index.js"],
      "env": {
        "OS_BASE_URL": "http://<CONTROLLER-IP>",
        "OS_PASSWORD_HASH": "<MD5-HASH>"
      }
    }
  }
}

Claude Desktop

In ~/.config/claude/claude_desktop_config.json eintragen:

{
  "mcpServers": {
    "opensprinkler": {
      "command": "node",
      "args": ["/vollstaendiger/pfad/zu/tools/mcp-server/dist/index.js"],
      "env": {
        "OS_BASE_URL": "http://<CONTROLLER-IP>",
        "OS_PASSWORD_HASH": "<MD5-HASH>"
      }
    }
  }
}

Passwort-Hash berechnen

echo -n "dein_admin_passwort" | md5sum | awk '{print $1}'

Tool-Überblick

Bereich	Beispiel-Tools
Controller-Status	`get_all`, `get_controller_variables`, `get_options`, `get_debug`, `get_system_resources`
Stationen und Programme	`get_stations`, `get_station_status`, `get_programs`, `manual_station_run`, `manual_program_start`, `change_program`
Sensoren und Logs	`get_sensors`, `get_sensor_values`, `get_sensor_log`, `get_sensor_types`, `backup_sensor_config`
OpenSprinklerPro-Funk	`get_ieee802154_config`, `get_zigbee_devices`, `get_zigbee_status`, `get_ble_devices`, `get_rainmaker_status`
Automation	`list_adjustments`, `configure_adjustment`, `list_monitors`, `configure_monitor`

Nützliche Kontextansicht

Der MCP-Server selbst hat keinen Controller-UI-Dialog. Für Diagnose vor Ort hilft System-Diagnose, um Firmwareversion, Speicher und Integrationen zu prüfen.

System-Diagnose