OpenDSS MCP Server

Leer en español

An MCP (Model Context Protocol) server that lets an AI assistant run OpenDSS, EPRI's open-source power distribution system simulator, through py-dss-interface. Claude Desktop, Claude Code or any other MCP client can compile circuits, run power flow, check voltage and thermal violations, simulate faults, extract Thévenin impedances, run hosting capacity and quasi-static time series (QSTS) studies, and plot results — through 20 typed tools that return structured data, not free text.

The point is reliability: the model never computes a number. OpenDSS does, and the assistant reads the result as JSON or Markdown with the inputs that produced it.

Tools

Each tool takes a single params object, for example opendss_compile_file(params={"dss_path": "...", "response_format": "json"}).

What it covers:

• Power flow: bus voltages in pu, line flows, loads, losses, convergence.

• Violations and loading: buses outside the voltage band and elements above their rated current, with the limits you pass.

• Short circuit: three-phase and single-line-to-ground faults at a bus or swept across buses, and positive- and zero-sequence Thévenin impedance.

• Hosting capacity: PV added in steps until a voltage, thermal or convergence limit binds, uniform or worst-case placement.

• QSTS: daily or yearly time series with the circuit's load shapes.

• Editing: typed add/edit/enable of PV, storage, loads, capacitors and regulators, with the values read back from OpenDSS.

Installation

Requires Python 3.10 or later. The OpenDSS engine ships with py-dss-interface, which works on Windows and Linux.

git clone https://github.com/jpsalamanca-co/opendss-mcp.git
cd opendss-mcp
pip install -e ".[dev]"   # [dev] adds pytest, pytest-asyncio and ruff
python -m pytest tests -q

Client configuration

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "opendss_mcp": {
      "command": "opendss-mcp",
      "env": { "OPENDSS_MCP_OUTPUT_DIR": "./results" }
    }
  }
}

To run it directly over stdio: opendss-mcp or python -m opendss_mcp.server.

Example

examples/ieee13/ includes the IEEE 13-node test feeder. With Master.dss compiled:

• it converges and has 15 buses;

• the minimum voltage between 1 and 100 kV is 0.924 pu;

• the nominal load is 3466 kW and 2102 kvar across 9 loads;

• a three-phase fault at bus 671 gives 4558.6 A.

The tests check those values, including one run over stdio as an MCP client would.

Scope

A calculation tool, not an engineering service. Results depend on the model you give it — a wrong source impedance converges just as cleanly as a right one — and are reviewed and signed by whoever holds the professional responsibility.

License

MIT, see LICENSE. OpenDSS (EPRI) is distributed under BSD-3-Clause and py-dss-interface under MIT; both are installed as dependencies, not redistributed here.