solarnetwork-mcp

Ein MCP-Server, der SolarNetwork-Solartelemetrie in Werkzeuge verwandelt, die ein KI-Agent aufrufen kann.

Keine Anmeldedaten erforderlich. Er läuft gegen die öffentlichen Endpunkte von SolarNetwork, wo ~52 Live-Solaranlagen echte Erzeugungs-, Einstrahlungs- und Wetterdaten veröffentlichen – mehrere davon aktualisieren sich minütlich, mit sechs Jahren Historie.

Was er kann

Solartelemetrie lesen

• Öffentliche Knoten ohne Anmeldedaten entdecken, nach Zeitzone oder Aktivität filtern

• Jeden Stream auf einer Anlage klassifizieren: Standortzähler, Wechselrichter, Einstrahlung, Wetter, ML-Anomalie

• Zeitreihen in jeder Aggregationsstufe von fünf Minuten bis zu einem Jahr abfragen

• Echte akkumulierte Energie aus Zählerständen statt gemittelter Leistung ermitteln

• Prüfen, ob ein Stream noch aktiv ist – anhand des Zeitstempels, nicht des Werts

Gerätefehler finden, mit Daten

• Wechselrichter-Ausfälle erkennen und den genauen Start- und Endtag festlegen

• Ein totes Gerät von einem unterscheiden, das erzeugt, aber keine Leistung meldet

• Ein Gerät erkennen, das verstummt ist, während seine Geschwister weiter melden

• Zählerstands-Rücksetzungen markieren, die stillschweigend jede Energiesumme korrumpieren, die sie überspannen

• Registrierungseinträge für Hardware entdecken, die nie existiert hat

• Pro Fehler verlorene Energie schätzen, skaliert von der Geschwisterleistung nach der eigenen Kapazität jedes Geräts

Keine Fehlalarme auslösen

• Die Erkennung ist peer-relativ, sodass Bewölkung nicht als Fehler registriert wird

• Einstrahlung wird als physikalische Wetterkontrolle verwendet, wo ein Pyranometer existiert

• Fehler, die bereits beim Öffnen des Fensters laufen, werden als Untergrenzen gekennzeichnet, nicht als erfundene Startdaten

• Anlagen, die nicht bewertet werden können, werden als nicht bewertet gemeldet, nie als gesund

Berichte schreiben, nach denen man handeln kann

• Priorisierte Arbeitsaufträge mit verständlicher Ursache, Belegen, nummerierten Schritten, Werkzeugen und Abnahmekriterien

• Druckbare PDF-Feldpakete mit Kontrollkästchen und einem Notizblatt

• Markdown zum Einfügen in ein Ticket oder JSON zur Weiterverarbeitung

• Durchgehend reines ASCII, damit nichts in einem PDF oder Ticketsystem zu schwarzen Kästen wird

Was er nicht kann

Wissenswert, bevor man sich darauf verlässt:

• Anlagen mit weniger als zwei Wechselrichtern können nicht bewertet werden. Der Peer-Vergleich braucht Peers. Das Werkzeug sagt das, statt ein sauberes Ergebnis zu melden.

• Keine Typenschild-Nennwerte. Öffentliche Knoten legen sie nicht offen, daher sind Verlustzahlen peer-skalierte Schätzungen, keine Garantieberechnungen.

• Die Fehlererkennung läuft auf Tages-Buckets. Ein Gerät, das sechs Stunden schweigt, ist unsichtbar.

• Die Stream-Klassifizierung hängt von einer Pfadkonvention ab. Anlagen, die Streams Main oder SMAInverter1 nennen, kommen unklassifiziert zurück.

Was er tatsächlich tut

Ohne ihn bedeutet die Beantwortung von „Ist an dieser Anlage etwas falsch?", die Knoten-ID zu kennen, den /datum/list-Endpunkt, dass aggregation=Day existiert, dass watts und wattHours unterschiedliche Fragen sind – und dann JSON zu lesen.

Mit ihm fragst du:

„Ist an Knoten 1000 etwas falsch? Wenn die Leistung niedrig ist, sag mir, ob es Wetter oder Ausrüstung ist."

und der Agent entdeckt die Streams der Anlage, wählt einen Datumsbereich, führt die Aggregation aus, vergleicht jeden Wechselrichter mit seinen Geschwistern und antwortet auf Englisch. Ein Satz hinein, eine Diagnose heraus.

Der Server übernimmt die Teile, in denen ein Sprachmodell schlecht ist – Anfragesignatur, Paginierung, Einheitensemantik, Wissen, welcher von neun Streams ein Wettersensor ist. Der Agent übernimmt die Teile, in denen er gut ist – entscheiden, was zu fragen ist, und die Antwort interpretieren.

In 60 Sekunden in Aktion sehen

npm install && npm run build && npm run smoke

Das treibt jedes Werkzeug über das echte MCP-Protokoll gegen Live-Daten. Kein Agent, kein API-Schlüssel, keine Konfiguration. Wenn es Ergebnisse für Knoten 1000 ausgibt, bist du gut aufgestellt.

Das deinem Agenten übergeben

Kopiere den gesamten Block unten in Claude Code, Cursor oder einen beliebigen MCP-fähigen Agenten. Er installiert den Server, verdrahtet sich selbst, beweist, dass die Installation funktioniert, und führt dann eine geführte Demo jeder Fähigkeit gegen Live-öffentliche Solaranlagen aus.

Set up and demo the solarnetwork MCP server for me.

1. INSTALL
   git clone https://github.com/gopisrikrishna/solarnetwork-mcp.git
   cd solarnetwork-mcp
   npm install
   npm run build

2. VERIFY THE INSTALL
   Run: npm run verify
   This runs 28 assertions against live public solar data. No credentials needed.
   Tell me how many passed. If any fail, show me which and stop.

3. CONNECT IT
   Register the server with yourself over stdio:
     command: node
     args:    ./dist/index.js   (run from the solarnetwork-mcp directory)
   The repo ships a .mcp.json that already does this. Restart/reconnect if your
   client needs it, then confirm you can see 10 tools and list their names.

4. DEMO IT
   Work through these against real public nodes and show me what you find.
   Explain your reasoning at each step, do not just dump JSON.

   a) DISCOVERY
      Which public nodes are live in US timezones? Then: what does node 1000
      measure, and how far back does its data go?

   b) ENERGY
      How much did node 1000 generate in July 2026? Use the right tool for a
      billing-shaped question and tell me why you chose it.

   c) FAULT DETECTION  <- the interesting one
      Run an asset review on node 1000 for 2026-01-01 to 2026-09-01.
      Tell me what broke, exactly when it started and ended, and what it cost.
      There is a real 79-day inverter outage in there, and a second fault where
      a device reports 0 watts while still generating. Explain the difference
      between those two failure modes and why it matters.

   d) NOT BEING FOOLED
      Run an asset review on node 949 for July 2026. It will find nothing.
      Explain why "no faults found" does NOT mean the site is healthy here.

   e) DATA INTEGRITY
      Run an asset review on node 781 for 2026-01-01 to 2026-09-01.
      Its site meter counter reset mid-year. Show me how the tool handles it and
      what would have gone wrong without that handling.

   f) CROSS-CHECK
      Node 392 publishes the platform's own ML anomaly streams. Compare what
      get_anomalies says against what the asset review found. Do they agree?

   g) REPORT
      Generate a PDF service report for node 1000 over the same window, written
      for an on-site technician. Save it and tell me the path, how many pages,
      and summarise the priority 1 jobs.

5. WRAP UP
   Tell me in plain language: what is wrong with node 1000, how much energy has
   been lost, and what you would send a technician to do first.

Selbst verifizieren

Da er auf öffentlichen Daten läuft, musst du keiner seiner Schlussfolgerungen blind vertrauen. Jedes Ergebnis ist von deinem eigenen Rechner aus unabhängig reproduzierbar:

npm install && npm run build && npm run verify

28 Assertions gegen feste historische Fenster auf Live-öffentlichen Knoten. Keine Anmeldedaten. Darunter:

Ein Fehlschlag bedeutet, dass der Server eine Regression hat oder SolarNetwork die Historie neu dargestellt hat. Jede Assertion druckt, was sie erwartet hat, gegen das, was sie bekommen hat, sodass die beiden leicht zu unterscheiden sind.

In deinen Agenten laden

Jeder Client will dieselben drei Fakten: node ausführen, dist/index.js übergeben, über stdio sprechen. Nur der Dateipfad unterscheidet sich.

Verwende den absoluten Pfad zu dist/index.js auf deinem Rechner. Schrägstriche funktionieren auch unter Windows.

Die hier eingecheckte .mcp.json verwendet stattdessen einen relativen Pfad, damit jeder, der das Repo klont, einen funktionierenden Server bekommt, ohne etwas zu bearbeiten. Das funktioniert nur für Clients, die den Server aus dem Projektstammverzeichnis starten, was Claude Code tut; andere Clients benötigen möglicherweise die absolute Form.

Claude Code

Bereits konfiguriert – .mcp.json liegt im Repo-Stammverzeichnis, sodass eine in diesem Verzeichnis gestartete Sitzung es automatisch aufnimmt. Bearbeite einfach den Pfad:

{
  "mcpServers": {
    "solarnetwork": {
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

Oder registriere es global von überall:

claude mcp add solarnetwork -- node /absolute/path/to/solarnetwork-mcp/dist/index.js

Claude Desktop

Bearbeite claude_desktop_config.json:

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

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

{
  "mcpServers": {
    "solarnetwork": {
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

Starte die App neu. Ein Werkzeugsymbol erscheint im Nachrichtenfeld.

Cursor

.cursor/mcp.json in deinem Projekt oder ~/.cursor/mcp.json für jedes Projekt. Derselbe mcpServers-Block wie oben.

Windsurf

~/.codeium/windsurf/mcp_config.json. Derselbe mcpServers-Block.

VS Code (Copilot-Agentenmodus)

.vscode/mcp.json – beachte, dass der Schlüssel servers ist, nicht mcpServers:

{
  "servers": {
    "solarnetwork": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

Zed

In settings.json unter context_servers:

{
  "context_servers": {
    "solarnetwork": {
      "command": { "path": "node", "args": ["/absolute/path/to/dist/index.js"] }
    }
  }
}

Alles andere

Jeder MCP-Client kann ihn über stdio starten:

node /absolute/path/to/solarnetwork-mcp/dist/index.js

Um ihn aus Code heraus zu steuern, ist scripts/smoke.mjs ein vollständiges funktionierendes Beispiel mit dem offiziellen TypeScript-SDK.

Prüfen, ob er geladen ist

Frage deinen Agenten: „Welche Solar-Werkzeuge hast du?" Du solltest zehn sehen. Wenn nicht, sind die üblichen Ursachen ein relativer Pfad, ein fehlendes npm run build oder dass der Client nicht neu gestartet wurde.

Die Werkzeuge

Entdeckung

Daten

Analyse

Berichte

Dinge, die du fragen kannst

Beginne hier – das sind echte, Live-Knoten:

Orientierung

Welche öffentlichen SolarNetwork-Knoten sind in US-Zeitzonen aktiv?

Was misst Knoten 1000, und wie weit reichen seine Daten zurück?

Gerade jetzt

Was erzeugt Knoten 892 gerade, und wie ist das Wetter dort?

Knoten 892 trägt einen Wettersensor und ein Pyranometer, sodass der Agent Temperatur, Bewölkung und Einstrahlung neben der Leistung erhält.

Diagnose – die interessanten

Ist an Knoten 1000 etwas falsch?

Knoten 892 listet sechs Wechselrichter, aber ich sehe keine Erzeugung. Was ist los?

Flotte

Ordne die Knoten 880, 884, 953, 964, 976, 987 und 1000 nach Leistung der letzten Woche. Welchen sollte ich zuerst ansehen?

Mehrstufig, wo die Verkettung sich zeigt

Finde einen Live-US-Knoten mit mindestens vier Wechselrichtern und Einstrahlungsdaten, dann diagnostiziere ihn für die letzten zwei Wochen.

Was du zurückbekommst

Echte Ausgabe von diagnose_site auf Knoten 1000:

[high] reporting-gap   /0145/S1/G1/GEN/101, /102, /103
       Registered on this node but returned no data for the window. That is a
       reporting or comms outage rather than a performance problem, so the
       device may well be generating.

[low]  inconsistent-instrumentation   /0145/S1/G1/INV/4
       Reports 0 W, but its `wh` field is non-zero (peak 16508), so it is moving
       energy. This device populates energy fields only, unlike its peers, so
       power-based comparison would wrongly read it as dead.

Dieser zweite Befund ist der Kern des gesamten Projekts. INV/4 liest 0 W, während seine drei Geschwister 400–700 W produzieren, was genau wie ein toter Wechselrichter aussieht – und eine frühere Version dieses Werkzeugs sagte das auch. Er ist nicht tot: Sein Zähler akkumulierte in diesem Monat 826 kWh. Wechselrichter an einer Anlage verwenden unterschiedliche Meldekonventionen. Ein Gesundheitscheck, der nur auf watts basiert, würde jede Nacht jemanden über einen funktionierenden Wechselrichter benachrichtigen.

Deine eigenen Knoten

Setze zwei Umgebungsvariablen, und der Server wechselt von den öffentlichen /pub-Endpunkten zu authentifizierten /sec-Endpunkten. Die Werkzeugoberfläche bleibt unverändert:

SN_TOKEN_ID=... SN_TOKEN_SECRET=... node dist/index.js

Die Authentifizierung ist SolarNetworks SNWS2-Schema – HMAC-SHA256 über eine kanonisierte Anfrage mit einem datumsbegrenzten Schlüssel. Es ist implementiert, aber ungtestet; ich habe kein Token-Paar zum Verifizieren.

Wie es funktioniert

Drei Dateien, ~900 Zeilen insgesamt:

• src/solarnetwork.ts – API-Client, Paginierung, Anfragesignatur

• src/analysis.ts – Quell-ID-Parsing, Standortdiagnose

• src/index.ts – die zehn Werkzeugdefinitionen

Die Werkzeug-Beschreibungen sind die eigentliche Schnittstelle. Ein Agent verkettet list_sources → query_datum nur dann korrekt, wenn die Beschreibungen sagen, wann man zu welchem greifen soll. Diese Formulierung richtig zu bekommen, war wichtiger für das Funktionieren als jede Datenverarbeitung.

Grenzen

• Knotenmetadaten sind auf öffentlichen Knoten leer, daher gibt es keine Typenschild-Kapazität und folglich keinen kapazitätsnormalisierten Vergleich. compare_fleet ordnet rohe Leistung und sagt das – eine große Anlage wird eine kleine gesunde überflügeln.

• list_public_nodes liest einen Punkt-in-der-Zeit-Scan (data/nodes.json), keine Live-Liste. Rufe list_sources auf, um zu bestätigen, bevor du dich auf einen Knoten verlässt.

• Kein Caching. Wiederholte Agentenaufrufe treffen die API erneut.

• Keine Unit-Tests. scripts/smoke.mjs ist eine Live-Sonde, keine Testsuite.

• SolarQuery erzwingt stillschweigend stündliche Aggregation für Bereiche über ~7 Tagen. query_datum gibt deine Aggregation unverändert weiter, sodass lange Bereiche gröbere Daten zurückgeben als angefordert.

Mehr Details: USAGE.md für funktionierende Beispiele und einen Aufwandsvergleich, DATA.md für das vollständige Inventar dessen, was öffentlich vs. anmeldegeschützt ist.

Lizenz

MIT