# OpenDSS MCP Server

*[Leer en español](README.es.md)*

An MCP (Model Context Protocol) server that lets an AI assistant run [OpenDSS](https://opendss.epri.com/), EPRI's open-source power distribution system simulator, through [py-dss-interface](https://github.com/PauloRadatz/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

| Group | Tools |
|---|---|
| Compile | `opendss_compile_file`, `opendss_compile_script` |
| Run | `opendss_run_command` |
| Query | `opendss_get_voltages`, `opendss_voltage_summary`, `opendss_get_loads`, `opendss_get_line_flows`, `opendss_get_loading`, `opendss_violations` |
| Edit | `opendss_edit_element`, `opendss_add_element`, `opendss_enable_elements` |
| Faults | `opendss_fault_3ph`, `opendss_fault_1ph`, `opendss_fault_sweep`, `opendss_thevenin_z1`, `opendss_thevenin_z0` |
| Studies | `opendss_hosting_capacity`, `opendss_run_qsts` |
| Output | `opendss_plot` |

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.

```bash
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`):

```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`.

| Variable | Default | Use |
|---|---|---|
| `OPENDSS_MCP_OUTPUT_DIR` | system temp folder | where plots are saved |

## 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](LICENSE). OpenDSS (EPRI) is distributed under BSD-3-Clause and py-dss-interface under MIT; both are installed as dependencies, not redistributed here.