Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenDSS MCP Server compile the IEEE 13-node feeder, run power flow, and report voltage violations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Group | Tools |
Compile |
|
Run |
|
Query |
|
Edit |
|
Faults |
|
Studies |
|
Output |
|
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.
Related MCP server: opendss-mcp-server
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 -qClaude 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.
Variable | Default | Use |
| system temp folder | where plots are saved |
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.
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.
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.
Create a new element (PVSystem, Storage, Load, Line, Capacitor, RegControl, InvControl, LoadShape...) from a properties dict and re-solve.
Typed alternative to opendss_run_command("New ..."): refuses to overwrite an existing element, verifies that OpenDSS created it and reads the properties back. Use element_class + name, not 'Class.Name' in name.
Args: params: AddElementInput with element_class, name, properties, solve.
Returns: Command executed, values read back and solve status.
Inputs: params (required). Returns: result
Compile an OpenDSS model from a .dss file on disk and run power flow.
Loads the circuit, solves it in snapshot mode, and returns a summary with convergence status, bus/line/load counts, and total losses.
Args: params: CompileFileInput with dss_path and optional buscoords_path.
Returns: Circuit summary with convergence, counts, and losses.
Inputs: params (required). Returns: result
Compile an OpenDSS circuit from inline DSS commands and run power flow.
Pass the complete DSS script as a multi-line string. The server writes it to a temporary file, compiles it, and solves in snapshot mode.
Args: params: CompileScriptInput with the DSS script text.
Returns: Circuit summary with convergence, counts, and losses.
Inputs: params (required). Returns: result
Edit properties of an existing element and re-solve.
Typed alternative to opendss_run_command("Edit ..."): checks that the element exists, builds the Edit command from the properties dict, reads the values back from OpenDSS and reports convergence. Fails on unknown properties instead of silently ignoring them.
Args: params: EditElementInput with element (Class.Name), properties, solve.
Returns: Command executed, values read back and solve status.
Inputs: params (required). Returns: result
Enable or disable all elements of a class, or only the named ones, and re-solve.
Typical use: disable every PVSystem to get the base case, or disable a Capacitor / RegControl to test its effect. Without names it runs BatchEdit Class..* enabled=yes|no.
Args: params: EnableElementsInput with element_class, enabled, names, solve.
Returns: Elements affected and solve status.
Inputs: params (required). Returns: result
Run a single-phase-to-ground (1F-G) fault at a specific bus.
Applies a 1-phase fault on the specified phase with given resistance and returns fault current magnitude, 3I0, per-phase voltages (pre/post), short-circuit power, and voltage sag impact.
Use two calls with different r_fault values (e.g., 0.01 and 1.0) to extract zero-sequence Thévenin impedance Z0_th via dual-fault method.
The circuit must be compiled first with opendss_compile_file or _script.
Args: params: Fault1PhInput with bus name, phase, and fault resistance.
Returns: Fault current, 3I0, Scc_1ph, and voltage impact summary.
Inputs: params (required). Returns: result
Run a three-phase fault at a specific bus.
Applies a 3-phase fault with specified resistance and returns fault currents (per phase), short-circuit power (Scc), and voltage sag impact (number of buses below 0.80 and 0.50 pu during the fault).
The circuit must be compiled first with opendss_compile_file or _script.
Args: params: FaultInput with bus name and fault resistance.
Returns: Fault currents, Scc, and voltage impact summary.
Inputs: params (required). Returns: result
Run three-phase faults at multiple buses to build a fault current curve.
Re-compiles the circuit for each bus to get clean, independent results. Useful for plotting Icc vs distance or sizing protection equipment.
Args: params: FaultSweepInput with list of buses.
Returns: Table of fault currents and Scc per bus.
Inputs: params (required). Returns: result
Get power flow (P, Q) and max current for every line.
Useful for identifying overloaded lines and understanding power distribution across the network.
Args: params: VoltageInput (only response_format is used).
Returns: Table of line flows sorted by current (descending).
Inputs: params (required). Returns: result
Get thermal loading (% of NormAmps) for every line and transformer.
Max phase current at terminal 1 against NormAmps and EmergAmps of the element. Shunt elements (capacitors) are skipped. Sorted by loading descending, so overloaded elements come first.
For transformers loading_pct is NOT the nameplate loading: NormAmps comes from normhkva, which defaults to 1.1 x kVA. Transformers also carry kva_nominal, i_nominal_a (winding 1) and loading_nominal_pct, the loading against nameplate kVA; report that one as "% of rated capacity".
Args: params: VoltageInput (only response_format is used).
Returns: Table with element, buses, i_max_a, norm_amps, emerg_amps, loading_pct (and, for transformers, kva_nominal, i_nominal_a, loading_nominal_pct).
Inputs: params (required). Returns: result
Get active and reactive power for every load in the circuit.
Returns nominal and actual (solved) kW/kvar for each load element.
Args: params: VoltageInput (only response_format is used).
Returns: Table of load powers.
Inputs: params (required). Returns: result
Get voltage magnitude (pu) for all buses in the compiled circuit.
Returns per-bus voltage data including average, min, max pu values, kV base, number of phases, distance from source, and coordinates. Filter by kv_base range to focus on MV or LV buses.
Args: params: VoltageInput with kv_min/kv_max filters.
Returns: Table of bus voltages sorted by voltage (ascending).
Inputs: params (required). Returns: result
Run a hosting capacity study by incrementally adding PV generation.
Tests multiple PV levels at the given load multiplier and reports, per level: Vmin/Vmax, voltage and thermal violation counts, worst loaded element, head flow (negative = reverse flow into the substation) and the binding constraint (voltage, thermal, convergence or none). Supports uniform distribution (equal PV per bus) and worst-case (all PV at the first bus given). Run it at minimum load (load_mult ~0.3): DER limits do not show at peak. The circuit is recompiled clean afterwards, so edits made with run_command/edit_element before the study are lost.
The circuit must be compiled from a file first (not from script).
Args: params: HostingCapacityInput with bus list, PV steps, transformer kVA, load_mult and limits.
Returns: Table per PV level plus hosting_capacity_kw (last level without violations) and the first binding constraint.
Inputs: params (required). Returns: result
Generate a voltage visualization plot and save it as PNG.
Supported plot types:
voltage_profile: Scatter plot of voltage vs distance from substation.
topology: Georeferenced network map colored by voltage level.
The circuit must be compiled and solved first.
Args: params: PlotInput with plot_type and kv_base filters.
Returns: Path to the generated PNG image file.
Inputs: params (required). Returns: result
Execute a single OpenDSS text command on the currently loaded circuit.
Useful for modifying the circuit after compilation (adding elements, changing parameters, setting modes, etc.).
Args: params: RunCommandInput with the DSS command string.
Returns: The DSS result string, or confirmation of execution.
Inputs: params (required). Returns: result
Run a quasi-static time series (QSTS) simulation.
Requires LoadShapes to be defined in the circuit model. Supports daily (24h), yearly (8760h), and dutycycle modes.
The circuit must be compiled first. LoadShapes must already be defined in the DSS model for time-varying behavior.
Args: params: QSTSInput with mode, stepsize, number of steps.
Returns: Convergence status and final-state voltage summary.
Inputs: params (required). Returns: result
Extract zero-sequence Thévenin impedance (Z0) at a bus.
Uses the dual-fault method with 1F-G faults: two single-phase faults with different R_fault, combined with Z1 extraction, to solve for R0_th and X0_th.
Returns both Z0 and Z1 (needed for the calculation). The circuit must be compiled first.
Args: params: TheveninZ0Input with bus name, phase, and two fault resistances.
Returns: R0_th, X0_th, Z0_th, plus Z1 data and supporting information.
Inputs: params (required). Returns: result
Extract positive-sequence Thévenin impedance (Z1) at a bus.
Uses the dual-fault method: two 3-phase faults with different R_fault values to algebraically solve for R1_th and X1_th.
The circuit must be compiled first.
Args: params: TheveninZ1Input with bus name and two fault resistances.
Returns: R1_th, X1_th, Z1_th, X/R ratio, and supporting data.
Inputs: params (required). Returns: result
Report buses outside [v_min, v_max] pu and elements above loading_max %.
Voltage limits apply per phase (bus v_min_pu / v_max_pu). Defaults are 0.95 / 1.05 pu and 100 % of NormAmps; pass the limits of the applicable standard (e.g. NTC 1340 / CREG) explicitly when they differ. Use it after every solve to verify the case before reporting results.
Args: params: ViolationsInput with limits and optional kV base filter.
Returns: Counts plus the lists of voltage and thermal violations.
Inputs: params (required). Returns: result
Get voltage statistics: min, max, mean, std, violation counts.
Provides a quick overview of the voltage regulation status including the number of buses below 0.95 pu and above 1.05 pu.
Args: params: VoltageInput with kv_min/kv_max filters.
Returns: Voltage statistics summary.
Inputs: params (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 20 tools
Most tools target clearly distinct operations (compile, query voltages/loads/flows, faults, QSTS, hosting capacity). There is deliberate overlap between opendss_run_command and the typed opendss_edit_element/opendss_add_element, and minor overlap between opendss_voltage_summary and opendss_violations, but the descriptions explicitly clarify the boundaries and when to prefer each.
Nearly all tools share the opendss_ prefix and a verb_noun or noun_action pattern (compile_file, get_voltages, run_qsts, fault_3ph, thevenin_z1). A few noun-only names (violations, plot, hosting_capacity) and the _3ph/_1ph suffix style deviate slightly but remain readable and predictable.
20 tools is on the heavier side but each maps to a genuinely distinct power-systems operation, so the count is justified rather than padded. It sits at the upper edge of comfortable scoping without obvious redundancy.
The surface covers the full analysis lifecycle: compile (file/script), raw command execution, element add/edit/enable, result queries (voltages, loads, flows, loading, violations), fault/Thevenin analysis, QSTS, hosting capacity, and plotting. Minor gaps like a dedicated delete_element or standalone re-solve are workable via run_command/enable_elements.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Solar, weatherization, EV charging, battery and heat-pump decision tools for AI agents.
Live US power market prices, load, generation, weather and permits for AI agents.
BusCalc 1.8.0 exposes 33 public tool families: 26 calculations and seven attributed data lookups. Calculate business pricing, finance, uncertainty, lease economics and emergency dispatch margins. Look up metals, energy, exchange rates, weather, BLS, USDA, Census and selected emergency sources, including NOAA gauges and USGS flood-impact points. Calculations include unsigned replayable receipts. Lookup results include source and observation dates where available. Road and outage coverage varies by location. The public Streamable HTTP endpoint is https://buscalc.com/api/mcp. Direct access is anonymous and rate limited. Full guide: https://buscalc.com/for-ai/
