OpenDSS-MCP-Server

MCP-Server, der es Claude ermöglicht, elektrische Verteilnetze MS/NS (Krankenhäuser, Gebäude, kritische Infrastruktur) mithilfe von OpenDSS über die Bibliothek OpenDSSDirect.py zu modellieren und zu simulieren.

1. Installation

Voraussetzungen: Python 3.10 oder höher.

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

Überprüfe, dass alles korrekt importiert wird:

python3 -c "import opendssdirect; import mcp; print('OK')"

Related MCP server: uam-analyst

2. Server isoliert testen (optional, aber empfohlen)

Bevor du ihn mit Claude verbindest, kannst du die Logik direkt mit dem beiliegenden Fallbeispiel testen:

python3 examples/hospital_basico.py

Wenn du "convergio": true siehst und Spannungen im Per-Unit-Bereich um 1.0, funktioniert der Server korrekt. Das Skript modelliert ein Krankenhaus mit Mittelspannungsanschluss, Verteiltransformator, OP-Tafel (kritische Last) und N-1-Kontingenzanalyse — siehe den Code in examples/hospital_basico.py für die vollständigen Details.

3. Verbindung mit Claude Desktop

Öffne (oder erstelle) die Konfigurationsdatei von Claude Desktop:

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

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

Füge diesen Eintrag hinzu (passe den absoluten Pfad an den Speicherort deines Projekts an):

{
  "mcpServers": {
    "opendss": {
      "command": "/ruta/absoluta/a/opendss-mcp/venv/bin/python3",
      "args": ["/ruta/absoluta/a/opendss-mcp/server.py"]
    }
  }
}

Unter Windows ist der Pfad zur ausführbaren Datei des venv normalerweise ...\opendss-mcp\venv\Scripts\python.exe.

Starte Claude Desktop vollständig neu. Du solltest das Werkzeug-Symbol (🔨) mit "opendss" als verbundenen Server sehen.

4. Verfügbare Werkzeuge

5. Beispiel für die Nutzung im Gespräch

Du kannst Claude nach der Verbindung zum Beispiel bitten:

„Modeliere ein Krankenhaus mit einem Mittelspannungsanschluss, einem 500-kVA-Transformator, einer Schalttafel für Operationssäle als kritische Last und einer Schalttafel mit 20 kW. Führe den Lastfluss aus. Sind die Spannungen im zulässigen Bereich?"

Oder für eine Ausfallanalyse:

„Simuliere den Verlust der Hauptleitung der NS-Ebene. Fällt die Operationssaal-Schalttafel aus?"

Oder zur Visualisierung:

„Erzeuge das einpolige Diagramm des aktuellen Stromkreises und öffne es im Browser."

5.1 Visualisierungsbeispiel

examples/visualizar_hospital.py erstellt dasselbe Krankenhausmodell und generiert zwei HTML-Diagramme: eines im Normalzustand und eines unter N-1-Kontingenz, um die Auswirkung des Verlusts des Einspeisers für die Operationssäle zu veranschaulichen.

python3 examples/visualizar_hospital.py

Jeder Bus wird als horizontale Linie gezeichnet, deren Farbe von der Spannung in pu abhängt (grün: 0,95–1,05 pu, gelb: 0,90–1,10 pu, rot: außerhalb des Bereichs oder spannungslos). Transformatoren, Lasten (rot, wenn sie kritisch sind) und Generatoren werden mit eigenen Symbolen dargestellt — es handelt sich nicht um einen generischen Graphen, sondern um ein einpoliges Diagramm mit realen elektrotechnischen Konventionen. Wenn du vor dem Erzeugen des Diagramms eine N-1-Ausfallsimulation durchgeführt hast, wird der entsprechende Schalter (mit Lücke und Beschriftung „ABIERTO") an der genauen Stelle des Netzes angezeigt, an der der Fehler aufgetreten ist.

5.2 Fallbeispiel mit mehreren Schalttafeln

examples/campus_hospitalario.py modelliert etwas, das näher an einem echten Krankenhaus liegt: einen einzelnen Mittelspannungsanschluss, der drei unabhängige Transformatoren speist (OP, Station, Verwaltung), jeweils mit mehreren Lasten, plus ein Notstromaggregat, das der kritischsten Schalttafel gewidmet ist. Zusätzlich wird eine N-1-Analyse auf einem der Transformatoren durchgeführt (nicht nur auf Leitungen).

python3 examples/campus_hospitalario.py

Das erzeugte Diagramm (diagrama_campus.html) unterscheidet bereits Busse (Kreise, Farbe nach Spannung), Transformatoren (kupferfarbene Punktlinien), Lasten (rot, wenn kritisch) und Generatoren (Symbole) sowie ein seitliches Bedienfeld mit einer Zusammenfassung des Netzes (Verluste, Konvergenz, Anzahl der Elemente).

6. Wichtige technische Hinweise

• Spannungsebenen (VoltageBases): OpenDSS verlangt, dass die Spannungsebenen des Netzes explizit angegeben werden (VoltageBases=[...]

  • CalcVoltageBases). Der Server erledigt das automatisch, sobald du einen Transformator hinzufügst. Du musst dich darum im normalen Gebrauch nicht kümmern.

• Persistenz: Das Modell lebt im Arbeitsspeicher, solange der MCP-Server läuft. Wenn du ein Modell speichern möchtest, kannst du obtener_netlist() verwenden und die resultierende .dss-Datei speichern.

• Einschränkungen: Die aktuelle Version erstellt nur symmetrische Dreiphasenmodelle und berücksichtigt keine Neutralleiterimpedanzen, Leitungsbündel, dynamische Lasten (Motoren) oder Transformatoren mit Stufenschaltern. Es wird davon ausgegangen, dass der Anschluss (normalerweise auf der MS-Seite) eine starre Spannungsquelle ist.

• Performance: Der Server verfügt über keine Datenbank. Das Netzmodell lebt ausschließlich im Speicher des OpenDSS-Prozesses. Es gibt kein „Speichern"-Kommando im üblichen Sinne: Um das Modell zu sichern, kannst du lista_activos() verwenden, um den aktuellen Netzzustand in Textform zu erhalten, oder den Abschnitt „Modell exportieren" (siehe unten), um einen OpenDSS-Skript-Ausdruck der erstellten Schaltung zu generieren.

61. Änderungshistorie

Siehe CHANGELOG.md für Details dazu, welche Werkzeuge in jeder Version hinzugefügt wurden, welche Korrekturen angewendet wurden und welche OpenDSS-Funktionen noch nicht abgedeckt sind (LoadShape, PVSystem, Storage, Zeitreihenanalyse, Oberschwingungen, Topologievisualisierung usw.). Dieses Projekt wird schrittweise erweitert, eine Fallstudie nach der anderen.Here is the German translation of the document:

OpenDSS MCP Server

Ein MCP-Server, der es Claude ermöglicht, elektrische Verteilnetze (MS/NS) – Krankenhäuser, Gebäude, kritische Infrastruktur – mit OpenDSS über die Bibliothek OpenDSSDirect.py zu modellieren und zu simulieren.

1. Installation

Voraussetzungen: Python 3.10 oder höher.

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

Prüfe, ob alles korrekt importiert wird:

python3 -c "import opendssdirect; import mcp; print('OK')"

2. Den Server isoliert testen (optional, aber empfohlen)

Bevor du ihn mit Claude verbindest, kannst du die Logik direkt testen:

python3 examples/hospital_basico.py

Wenn du "convergió": true und Spannungen in p.u. nahe 1.0 siehst, funktioniert der Server korrekt. Das Skript modelliert ein Krankenhaus mit Mittelspannungs-Einspeisung, Verteilungstransformator, Operationssaal-Schaltanlage (kritische Last) und N-1-Analyse – siehe den Code in examples/hospital_basico.py für Details.

3. Verbindung zu Claude Desktop herstellen

Öffne die Konfigurationsdatei von Claude Desktop:

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

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

Füge diesen Eintrag hinzu (passe den absoluten Pfad zu deinem Projekt an):

{
  "mcpServers": {
    "opendss": {
      "command": "/ruta/absoluta/a/opendss-mcp/venv/bin/python3",
      "args": ["/ruta/absoluta/a/opendss-mcp/server.py"]
    }
  }
}

Unter Windows lautet der Pfad zur venv-Python-Datei normalerweise ...\opendss-mcp\venv\Scripts\python.exe.

Starte Claude Desktop vollständig neu. Du solltest das Werkzeug-Symbol (🔨) mit „opendss“ als verbundenen Server sehen.

4. Verfügbare Werkzeuge

5. Beispiel für den Einsatz im Gespräch mit Claude

„Modela un hospital con acometida de 13.2 kV y un transformador de 500 kVA a 0.4 kV. Conecta tres tableros: quirófanos (crítico), hospitalización y administración. Agrega un generador de respaldo en el tablero de quirófanos. Corre el flujo de potencia y muéstrame los voltajes por bus."

„Simula la pérdida del alimentador principal de MT. ¿Qué voltajes se obtienen en los tableros?"

„Genera el diagrama unifilar del circuito actual."

3. Mit Claude Desktop verbinden

Öffne die Konfigurationsdatei von Claude Desktop:

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

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

Füge folgenden Eintrag hinzu (passe den absoluten Pfad an deinen Projektordner an):

{
  "mcpServers": {
    "opendss": {
      "command": "/ruta/absoluta/a/opendss-mcp/venv/bin/python3",
      "args": ["/ruta/absoluta/a/opendss-mcp/server.py"]
    }
  }
}

Unter Windows lautet der Pfad zur Python-Executable der venv normalerweise ...\opendss-mcp\venv\Scripts\python.exe.

Starte Claude Desktop vollständig neu. In der Werkzeugleiste (🔨) sollte „opendss“ als verbundener Server erscheinen.

4. Verfügbare Werkzeuge

5. Beispiel für die Nutzung

Nach der Verbindung kannst du zum Beispiel sagen:

„Modelliere ein Krankenhaus mit einer Mittelspannungs-Einspeisung, einem Verteilungstransformator und zwei Schaltanlagen: eine für den OP-Trakt (kritisch) und eine für die allgemeine Beleuchtung. Führe den Lastfluss aus und zeige mir die Spannungen an den Bussen."

Oder für eine N-1-Analyse:

„Simuliere den Ausfall des Hauptspeisers. Welche Lasten sind betroffen?"

Oder:

„Erstelle das Einliniendiagramm und öffne es im Browser."

6. Grenzen und bekannte Einschränkungen

• Die Modelle sind statisch (eine Momentaufnahme). Zeitabhänige Lasten (LoadShape), Erzeugung (PVSystem, Storage) und Leistungsschalter-Sequenzen sind noch nicht implementiert.

• Die calcular_arc_flash-Funktion verwendet eine vereinfachte Methode (Lee-Gleichung) – nicht für reale Schutzbemessung oder Sicherheitsvorschriften verwenden.

• Es wird ein einziges Transformatorverhältnis angenommen; Stufenschalter werden nicht modelliert.

• Leitungen werden als symmetrische Komponenten (R1, X1, R0, X0) modelliert; die vollständige Kabelgeometrie wird nicht unterstützt.

6. Nächste Schritte / Erweiterungen

Geplante Funktionen und bekannte Einschränkungen findest du in der Datei CHANGELOG.md und in den offenen Issues. Aktuell fehlen unter anderem: Zeitreihen-Lastprofile (LoadShape), Photovoltaik (PVSystem), Speicher (Storage), Oberschwingungsanalyse, Schutzkoordination und die Integration in andere MCP-Clients als Claude Desktop.

Falls die Übersetzung bestimmter Abschnitte (z. B. Codeblöcke, Platzhalter wie GXP1–GXP5 oder die Markdown-Tabellen) unverändert bleiben soll, lass es mich wissen.