Electric MCP — OpenDSS

MCP server for modeling, simulating, and inspecting MV/LV electrical networks with OpenDSS via OpenDSSDirect.py.

The project's goal is to offer an MCP client high-level electrical tools —creating circuits, adding elements, solving power flow, short circuit, contingencies, and generating one-line diagrams— without giving it direct, unrestricted access to the OpenDSS interpreter.

In addition to the ChatGPT/MCP dialogue, the project can maintain a persistent HTML workspace that acts as a technical viewer for the active circuit. The HTML does not contain a second chatbot nor use a model API: ChatGPT remains the conversational interface, OpenDSS remains the electrical engine, and the workspace is solely a structured view of the state and results.

Status: educational / experimental project. It does not replace a professional electrical study or validated software for design, protection coordination, or arc flash safety.

1. Installation

Requirements: Python 3.10 or higher.

git clone https://github.com/NoeCalle/MCP-Electrico.git
cd MCP-Electrico

python -m venv venv

Windows:

venv\Scripts\activate
pip install -r requirements.txt

Linux/macOS:

source venv/bin/activate
pip install -r requirements.txt

Quick verification:

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

Related MCP server: uam-analyst

2. Testing without an MCP client

The examples import the functions from server.py directly:

python examples/hospital_basico.py
python examples/visualizar_hospital.py
python examples/campus_hospitalario.py
python examples/arc_flash_campus.py
python examples/unifilar_tecnico.py
python examples/workspace_hospital.py

unifilar_tecnico.py generates unifilar_tecnico.svg and unifilar_tecnico.html. workspace_hospital.py generates a persistent workspace_hospital.html with the embedded one-line diagram, calculation state, model data, and buttons for printing/PDF and SVG download.

To run the regression suite:

pip install -r requirements-dev.txt
python -m pytest -q

GitHub Actions runs pytest, generates the technical one-line diagram and the reference workspace, and keeps both as artifacts in each PR.

3. Connecting to an MCP client

Example for Claude Desktop on Windows:

{
  "mcpServers": {
    "opendss": {
      "command": "C:\\ruta\\MCP-Electrico\\venv\\Scripts\\python.exe",
      "args": ["C:\\ruta\\MCP-Electrico\\server.py"]
    }
  }
}

On macOS/Linux, use the venv Python executable and the absolute path to server.py.

4. Available tools

5. Persistent HTML workspace

The workspace sets a stable path for the active circuit. MCP tools that change the model or its representation regenerate that file automatically.

Conceptual example:

configurar_workspace(
    "workspace.html",
    titulo="Hospital — Sistema eléctrico",
    auto_regenerar=True,
)

crear_circuito("hospital", 22.9)
agregar_transformador(...)
agregar_linea(...)
agregar_carga(...)
ejecutar_flujo_potencia()

5.1 State and revisions

The workspace distinguishes:

• EMPTY: no usable model exists;

• MODIFIED: the model changed after the last solution;

• SOLVED: the current revision matches the solved revision;

• ERROR: a relevant electrical error/non-convergence exists.

model_revision, solved_revision, and visual_revision are maintained. An electrical change automatically invalidates previous studies; a purely visual change does not invalidate a correct solution.

Each study keeps the revision with which it was calculated and exposes a valid flag. Thus a historical result can remain traceable without being presented as current.

5.2 HTML and export

The initial version includes:

• embedded SVG one-line diagram;

• summary of buses, feeders, loads, and losses;

• Data tab;

• embedded and versioned JSON snapshot;

• Print / PDF button, based on window.print() and print CSS;

• Download SVG button;

• Reload file button.

The HTML is self-contained and uses no remote dependencies. The file is rewritten automatically, but an already-open local tab must be refreshed to read the new version. A local server/watch for live updates is left for a later phase.

The guide is in docs/WORKSPACE.md and the full architectural decision in docs/decisions/ADR-0001-workspace-persistente.md.

6. Technical SVG one-line diagram

The visualization avoids the aesthetic of a generic graph. The renderer interprets the electrical model to show physical busbars only when appropriate and collapses purely logical buses by default.

Main principles:

1. ordered main power flow;

2. clearly hierarchical physical busbars;

3. orthogonal and ordered feeders;

4. head-of-line protection;

5. consistent symbology for source, transformer, panelboard, motor, ATS, UPS, generator, and ground;

6. engineering labels independent of the internal OpenDSS name;

7. distinguishable visual protections: breaker, MCCB, ACB, fuse, and disconnector;

8. clean ingenieria mode and diagnostico mode with additional information;

9. vertical or horizontal orientation;

10. open elements and de-energized buses visually differentiated.

Example:

agregar_carga(
    "motor_bomba",
    "mcc_01",
    kw=75,
    kvar=30,
    kv=0.48,
    tipo_visual="motor",
)

configurar_alimentador_unifilar(
    "Line.f_critico",
    dispositivos=["ats", "ups"],
    fuente_alterna="Generator.ge_01",
    proteccion="mccb",
    conductor="3x50 mm2 Cu XLPE",
)

ejecutar_flujo_potencia()
generar_diagrama_unifilar("hospital.html", titulo="Hospital — Diagrama unifilar")

If the path ends in .html, a companion vector .svg is also generated. The complete visual specification is in docs/UNIFILAR_TECNICO.md.

ATS and UPS are, for now, representation annotations. They let the one-line diagram document the intended architecture without claiming that OpenDSS already models their internal electronics, transfer, autonomy, or fault contribution. Those annotations do not change impedances or electrical results.

7. N-1 contingencies: coherent state

simular_perdida_alimentador() distinguishes two working modes.

With restaurar=True, the element is opened, OpenDSS solves the contingency, the results are captured, and then the exact original state is restored and re-solved.

With restaurar=False, the element remains open and the circuit stays solved in contingency for inspection and visualization.

The workspace records the contingency study along with the model revision it corresponds to.

8. Critical loads

Loads marked with critica=True are kept as model metadata. During a contingency, for each critical load, its bus, per-unit voltages, energization indicator, and the list of critical loads without voltage are returned.

The internal threshold used to distinguish an essentially de-energized busbar from an energized one is not a service quality compliance criterion.

9. DSS export

obtener_netlist() exports the circuit and returns the directory, Master.dss, number of files, and content of each generated .dss file.

10. Arc Flash: scope and safety

estimar_arc_flash_lee() implements only the simplified Lee equation for learning and order-of-magnitude estimation.

It does not implement the full empirical IEEE 1584-2018 model and does not convert incident energy into a PPE category. calcular_arc_flash() is kept as a compatible alias.

11. Short circuit

dss.Bus.Isc() returns interleaved real and imaginary components. The server explicitly calculates the magnitude of each phasor:

|I| = sqrt(Re(I)^2 + Im(I)^2)

When integrating it with the workspace, the FaultStudy is kept as a study and then a power flow solution is restored before regenerating the viewer. This avoids mixing solution modes in the persistent one-line diagram.

12. Generators and UPS

agregar_generador_respaldo() represents a genset via the OpenDSS Generator object. A power-electronics-based UPS is not presented as equivalent to a synchronous generator.

13. Architecture

MCP-Electrico/
├── server.py
├── mcp_electrico/
│   ├── __init__.py
│   ├── core.py
│   ├── visualization.py
│   ├── visual_state.py
│   ├── visual_symbols.py
│   ├── workspace_state.py
│   └── workspace.py
├── docs/
│   ├── UNIFILAR_TECNICO.md
│   ├── WORKSPACE.md
│   └── decisions/
│       └── ADR-0001-workspace-persistente.md
├── examples/
│   ├── unifilar_tecnico.py
│   └── workspace_hospital.py
├── tests/
├── requirements.txt
└── requirements-dev.txt

• server.py: MCP tools and orchestration.

• core.py: electrical logic and OpenDSS state.

• visualization.py: topological interpretation, layout, and SVG rendering.

• visual_symbols.py: vector symbol library.

• visual_state.py: visual metadata that does not alter the calculation.

• workspace_state.py: revisions, validity, and snapshot contract.

• workspace.py: rendering/auto-generation of the persistent HTML.

14. Current limitations

• several elements use positive-sequence parameters R1/X1;

• there is still no technical cable library with parameter provenance;

• there is no detailed R0/X0 modeling or impedance matrices;

• there are no TCC curves or protection coordination;

• ATS/UPS can be documented visually, but they do not yet have their own detailed electrical model;

• there is no LoadShape, PV, Storage, capacitors, harmonics, or annual simulation;

• the workspace does not persist the project between process restarts;

• an open local HTML requires manual refresh to read a regeneration;

• the specific voltage drop, flow, short-circuit, and contingency views are planned on the v1 snapshot but are not yet part of the workspace;

• the SVG is a technical one-line diagram, not a contractual CAD drawing or a complete IEC/ANSI standards library;

• Arc Flash is only an educational Lee estimation.

The next leap for the workspace will be incorporating visual interaction with element selection and, afterward, flow and voltage drop overlays without breaking the snapshot contract defined in this phase.