Enphase Solar MCP-Server

Ein MCP-Server, der Claude Desktop mit der offiziellen Enphase Developer API v4 verbindet. Standardmäßig schreibgeschützt; Schreibzugriffe für Batterie und EV-Ladegeräte sind über ein Opt-in-Flag verfügbar. Kein Passwort-Scraping — sauberes OAuth 2.0 für den Zugriff auf Ihre eigenen Systemdaten.

Was Sie erhalten

30 Lese-Tools (immer aktiv), gruppiert nach Zweck:

3 Schreib-Tools (Opt-in über ENPHASE_ENABLE_WRITES=1):

Diese ändern das Verhalten der physischen Geräte ohne Rückgängig-Funktion. Lassen Sie sie deaktiviert, es sei denn, Sie wünschen explizit eine LLM-gesteuerte Kontrolle Ihrer Hardware.

Plan- und Hardware-Hinweise

• Abonnement-Plan. Der kostenlose Watt-Plan deckt Systemdetails sowie Produktion/Verbrauch auf Standortebene ab — ausreichend für die meisten Lese-Tools. Telemetrie pro Gerät, Storm Guard und einige Batterie-Endpunkte erfordern möglicherweise Kilowatt oder höher. Ein 401-Fehler bei einem bestimmten Tool bedeutet normalerweise „Plan upgraden“.

• Hardware erforderlich. Batterie-Tools benötigen eine Enphase IQ Battery / Encharge. EV-Ladegerät-Tools benötigen ein Enphase IQ EV-Ladegerät (Tesla Wall Connectors und Ladegeräte von Drittanbietern sind für Enphase unsichtbar). Ein 404-Fehler bei einem dieser Tools bedeutet normalerweise „Sie besitzen dieses Gerät nicht“.

• API-Fehler werden unverändert weitergegeben, damit Sie erkennen können, welcher Fall vorliegt.

Voraussetzungen

• Python 3.11+

• Ein Enphase Enlighten-Konto mit Ihrem System

• Ein Enphase Developer-Konto unter https://developer-v4.enphase.com (der kostenlose Watt-Plan reicht aus — 1.000 Aufrufe/Monat)

Einrichtung

1. Entwickler-App registrieren

1. Registrieren Sie sich unter https://developer-v4.enphase.com

2. Abonnieren Sie den Watt-Plan (kostenlos)

3. Erstellen Sie eine neue Anwendung

4. Setzen Sie den Redirect URI auf https://api.enphaseenergy.com/oauth/redirect_uri (Standard)

5. Notieren Sie sich Ihren API Key, Client ID und Client Secret

2. System-ID finden

Melden Sie sich unter https://enlighten.enphaseenergy.com an — Ihre System-ID finden Sie in der URL: https://enlighten.enphaseenergy.com/web/{SYSTEM_ID}/today

(Falls Sie sie noch nicht kennen, lassen Sie sie in .env leer und verwenden Sie get_systems, sobald der Server läuft, um sie zu ermitteln.)

3. Installation

cd enphase-mcp
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt

4. Anmeldedaten konfigurieren

cp .env.example .env
# Edit .env and fill in API key, client ID, client secret, system ID
# (Optional) uncomment ENPHASE_ENABLE_WRITES=1 to expose write tools.

5. Einmaligen Authentifizierungsablauf ausführen

python auth_setup.py

Das Skript gibt eine Autorisierungs-URL aus. Stellen Sie sicher, dass Sie im selben Browser bereits bei Enlighten angemeldet sind, öffnen Sie dann die URL und genehmigen Sie den Zugriff für Ihr System. Sie werden auf eine Seite weitergeleitet, die Ihren Autorisierungscode anzeigt. Kopieren Sie diesen und fügen Sie ihn im Terminal ein.

Dies erstellt eine tokens.json mit Ihren Zugriffs- und Aktualisierungs-Tokens. Von da an aktualisiert sich der Client bei jedem API-Aufruf automatisch.

6. Mit Claude Desktop verbinden

Bearbeiten Sie die claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "enphase": {
      "command": "/absolute/path/to/enphase-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/enphase-mcp/server.py"]
    }
  }
}

Starten Sie Claude Desktop vollständig neu (⌘Q unter macOS, nicht nur das Fenster schließen). Sie sollten nun eine Tool-Anzeige in der Chateingabe sehen. Fragen Sie Dinge wie „Wie viel haben wir heute im Vergleich zu gestern produziert?“ oder „Was war unser produktivster Tag in diesem Monat?“.

Verhalten bei Token-Aktualisierung

• Zugriffstokens sind 1 Stunde gültig

• Aktualisierungstokens sind bei Inaktivität ca. 1 Woche gültig — jeder API-Aufruf setzt den Timer zurück

• Wenn die Aktualisierung fehlschlägt, führen Sie python auth_setup.py erneut aus

Optional: Automatischer Keepalive

Wenn Sie Enphase nicht wöchentlich abfragen, können Sie keepalive.py nach einem Zeitplan ausführen, um das Aktualisierungstoken aktiv zu halten. Es ruft /systems einmal auf und protokolliert dies in keepalive.log. Erstellen Sie unter macOS einen LaunchAgent unter ~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist, der auf das Python des venv und keepalive.py verweist, mit einem StartInterval von 259200 (3 Tage) — das gibt ca. 4 Tage Puffer innerhalb des 7-tägigen Inaktivitätsfensters. Laden Sie ihn mit launchctl bootstrap gui/$(id -u) <plist>.

Weitere Endpunkte hinzufügen

Die Enphase v4 API-Oberfläche ist unter https://developer-v4.enphase.com/docs dokumentiert und die vollständige Swagger-Spezifikation finden Sie unter https://developer-v4.enphase.com/swagger/spec/System_API.json (47 Endpunkte; dieser Server kapselt die meisten davon, überspringt jedoch Telemetrie pro Mikro-Wechselrichter, Wärmepumpen-Endpunkte, systemübergreifende Suche und einige spezialisierte Zähler-Endpunkte).

Um einen hinzuzufügen, fügen Sie eine neue Methode in server.py nach dem bestehenden Muster hinzu:

@mcp.tool()
def my_new_tool(some_param: str) -> dict:
    """What this returns."""
    sid = client.require_system_id()
    return client.get(f"/systems/{sid}/some_endpoint", params={"x": some_param})

Fehlerbehebung

401 bei bestimmten Endpunkten: Problem mit der Plan-Stufe. Die meisten Lesezugriffe funktionieren mit Watt; einige erfordern Kilowatt+.

404 bei Batterie- / EV-Ladegerät-Endpunkten: Sie besitzen diese Hardware nicht in Ihrem System.

406 bei der Auth-URL: Sie sind im Browser nicht bei Enlighten angemeldet. Melden Sie sich zuerst an und öffnen Sie dann die Auth-URL erneut.

„No tokens found“: Führen Sie python auth_setup.py aus.

Claude sieht die Tools nicht: Überprüfen Sie die Claude Desktop-Protokolle unter ~/Library/Logs/Claude/ (macOS) oder %APPDATA%\Claude\logs\ (Windows). Die meisten Probleme sind Probleme mit absoluten Pfaden in der claude_desktop_config.json.