OpenDSS MCP Server

How to use

You interact with the server via an MCP client that speaks in natural language. Start with a high-level goal such as loading a feeder, running a power flow, or optimizing solar placement. The server translates your request into OpenDSS operations, returns structured results, and provides visualization outputs when appropriate. You can chain tasks in a single conversation, for example loading a feeder, running a power flow, and requesting voltage and loss summaries. If you need to adjust a study, simply ask for alternative placements, different solar capacities, or a time-series scenario. The system supports multiple tools to perform loading, analysis, optimization, time-series simulations, and visualizations, returning clear success messages and metrics for each step.

How to install

# Install prerequisites
pip install -U pip

# Use the MCP server entry via stdio locally
# Run from your project root or wherever you keep the source
python -m opendss_mcp.server

# If you need to point to the source path for imports, set PYTHONPATH accordingly
export PYTHONPATH=/absolute/path/to/opendss-mcp-server/src
```

Note: The server is intended to be started as a local stdio MCP process. Your CLI or orchestrator should launch the command shown above and communicate using MCP protocol. Ensure the Python environment has access to the OpenDSS engine and its Python bindings as required by your setup.

Configuration and usage notes

You connect to the server as a local process. The example configuration shows starting the server with Python and pointing the Python path to the source directory that contains the MCP server modules.

{
  "type": "stdio",
  "name": "opendss",
  "command": "python",
  "args": ["-m", "opendss_mcp.server"],
  "env": {
    "PYTHONPATH": "/absolute/path/to/opendss-mcp-server/src"
  }
}

Troubleshooting tips

If you encounter connection issues, verify that the MCP process starts without errors and that the host running the MCP client can reach the stdio stream. Check that the PYTHONPATH points to the correct source location and that any required OpenDSS dependencies are installed. Review any error messages from the MCP client for hints about missing modules or import errors, and ensure your Python environment matches the project’s requirements.

Examples of typical workflows

Common workflows include loading a test feeder, performing a power flow, and then running a DER optimization. You can then request visualizations such as voltage profiles or hosting capacity curves, and finally generate an executive summary or a detailed report.

Tools overview

Seven MCP tools enable end-to-end power system analysis and visualization: loading IEEE feeders, conducting power flow analysis, checking voltage quality, performing hosting capacity and time-series studies, optimizing DER placement, and creating professional visualizations. Each tool returns actionable metrics and supports before/after comparisons where applicable.

Examples of commands you can ask for

Load a specific feeder, run a power flow, and view voltage range and losses. Optimize DER placement for loss reduction and voltage improvement. Generate a hosting capacity curve for a feeder. Run a 24-hour time-series simulation and inspect energy metrics. Generate publication-quality plots and an executive summary report.

Status messages you may see

The server responds with concise confirmations like ✓ Loaded feeder, ✓ Converged, and ✓ Visualization saved, followed by key metrics such as voltage ranges, total losses, and location identifiers for optimized assets.

Notes on environment and language

This MCP server is implemented in Python and is started as a local stdio process. Ensure your environment has the necessary Python version and dependencies to import and run the MCP server and to interface with the OpenDSS engine.

Getting results and visuals

Results include structured data (numbers, units, and bus IDs) and optional visualization outputs. Visualizations can be generated for voltage profiles, network diagrams, time-series plots, hosting capacity curves, and harmonics spectra.

Python API usage example

You can access the server’s capabilities from Python scripts by launching the MCP client process and sending requests via the MCP protocol. The server exposes tools for feeder loading, power flow, voltage checks, hosting capacity, DER optimization, time-series, and visualization APIs, which return structured results suitable for automation and reporting.

Workflow example

Engineer: Load the IEEE13 feeder and baseline it. Claude responds with a loaded feeder. Engineer: Find optimal locations for 5 MW total solar across 5 sites. Claude returns site mappings and total loss reduction. Engineer: Run a time-series with summer load and solar profiles. Claude provides energy savings and peak demand metrics, with plots. Engineer: Generate an executive summary report. Claude creates a report outline or attachable document.

What you get visually

Voltage profiles, network diagrams, multi-panel time-series plots, hosting capacity curves, and harmonics spectra are produced automatically and can be saved at publication quality.

Additional resources

You can extend your setup with more feeders, time-series profiles, and control curves to tailor the analysis to your utility’s needs.

load_feeder

Load IEEE feeder models (IEEE 13/34/123 bus) and populate topology and component data for subsequent analyses.

run_power_flow_analysis

Perform power flow studies with convergence checking and voltage profiling across the network.

check_voltages

Assess voltage quality and identify violations, with before/after comparisons.

analyze_capacity

Evaluate hosting capacity and identify limiting constraints across locations.

optimize_der

Place DER resources (solar, storage, etc.) to minimize losses and improve voltages with smart inverter controls.

run_timeseries

Execute time-series simulations with load and generation profiles to analyze energy metrics.

create_visualization

Generate professional plots and diagrams such as voltage profiles, network topologies, and curves.