You: "Load IEEE13 feeder, optimize 2MW solar placement, and show voltage improvements"

Claude: ✓ Loaded IEEE13 (13 buses)
        ✓ Optimized solar placement → Bus 675
        ✓ Loss reduction: 32.4%
        ✓ Voltage violations fixed: 3
        [Voltage profile visualization shown]

# Clone the repository
git clone https://github.com/ahmedelshazly27/opendss-mcp-server.git
cd opendss-mcp-server

# Install the package
pip install -e .

# Verify installation
python -c "from opendss_mcp import server; print('✓ OpenDSS MCP Server installed successfully!')"

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

Load the IEEE13 feeder and run a power flow analysis. Show me the voltage range and total losses.

✓ IEEE13 feeder loaded (13 buses, 11 lines)
✓ Power flow converged in 8 iterations

Voltage Range: 0.9542 - 1.0500 pu
Total Losses: 116.2 kW + 68.3 kVAr

Optimize placement of 2000 kW solar to minimize losses on the IEEE13 feeder.
Show the optimal location and improvement metrics.

✓ Optimal Location: Bus 675

Improvements:
  • Loss Reduction: 37.7 kW (32.4%)
  • Voltage Improvement: +0.017 pu
  • Violations Fixed: 3

[Voltage profile visualization shown]

Analyze solar hosting capacity at bus 675 with 500 kW increments up to 5000 kW.
Generate a capacity curve showing the limiting constraint.

✓ Maximum Capacity: 2500 kW
✓ Limiting Constraint: Overvoltage (1.05 pu)

At 3000 kW: Bus 675 exceeds 1.05 pu limit

[Capacity curve visualization shown]

Run a 24-hour time-series simulation with residential load profile and solar generation.
Show voltage variations and energy losses throughout the day.

✓ 24 timesteps completed (100% convergence)

Summary:
  • Energy Delivered: 78,234 kWh
  • Energy Losses: 2,364 kWh (3.02%)
  • Peak Load: 3,842 kW at 18:00
  • Voltage Violation Hours: 2

[Time-series plots shown]

from opendss_mcp.tools.feeder_loader import load_ieee_test_feeder
from opendss_mcp.tools.power_flow import run_power_flow
from opendss_mcp.tools.der_optimizer import optimize_der_placement
from opendss_mcp.tools.visualization import generate_visualization

# Load feeder
result = load_ieee_test_feeder('IEEE13')
print(f"✓ Loaded {result['data']['num_buses']} buses")

# Run power flow
pf_result = run_power_flow('IEEE13')
print(f"✓ Converged: {pf_result['data']['converged']}")
print(f"  Voltage: {pf_result['data']['min_voltage']:.4f} - {pf_result['data']['max_voltage']:.4f} pu")

# Optimize DER placement
der_result = optimize_der_placement(
    der_type="solar",
    capacity_kw=2000,
    objective="minimize_losses"
)
print(f"✓ Optimal Bus: {der_result['data']['optimal_bus']}")
print(f"  Loss Reduction: {der_result['data']['improvement_metrics']['loss_reduction_pct']:.1f}%")

# Generate visualization
viz_result = generate_visualization(
    plot_type="voltage_profile",
    data_source="circuit",
    options={"save_path": "voltage_profile.png", "dpi": 300}
)
print(f"✓ Visualization saved: {viz_result['data']['file_path']}")

Engineer: "Load the Al-Ahmadi-North feeder model and baseline it"
Claude: ✓ Loaded (87 buses, 12.5 MVA peak load)

Engineer: "Find optimal locations for 5 MW total solar across 5 sites"
Claude: ✓ Optimized placement:
          Site 1: Bus 42 (1.2 MW)
          Site 2: Bus 58 (1.1 MW)
          Site 3: Bus 71 (0.9 MW)
          Site 4: Bus 23 (1.0 MW)
          Site 5: Bus 65 (0.8 MW)
        ✓ Total loss reduction: 18.3%
        ✓ No voltage violations

Engineer: "Run time-series with summer load and solar profiles"
Claude: ✓ Simulation complete
        ✓ Energy savings: 4,200 MWh/year
        ✓ Peak demand reduction: 8.2%
        [Daily profile plots shown]

Engineer: "Generate executive summary report"
Claude: ✓ Report generated with:
          • Technical findings
          • Cost-benefit analysis
          • Implementation recommendations
          [PDF report attached]

# Generate all example plots
cd examples
python generate_plots.py

# Check output in examples/plots/
ls -lh examples/plots/

┌─────────────────────────────────────────────────────────────┐
│                        Claude Desktop                        │
│                  (Natural Language Interface)                │
└────────────────────────────┬────────────────────────────────┘
                             │ MCP Protocol
┌────────────────────────────▼────────────────────────────────┐
│                    OpenDSS MCP Server                        │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  7 MCP Tools:                                          │ │
│  │  • load_feeder                                         │ │
│  │  • run_power_flow_analysis                             │ │
│  │  • check_voltages                                      │ │
│  │  • analyze_capacity                                    │ │
│  │  • optimize_der                                        │ │
│  │  • run_timeseries                                      │ │
│  │  • create_visualization                                │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Utilities:                                            │ │
│  │  • Validators • Formatters • Harmonics • Controls      │ │
│  └────────────────────────────────────────────────────────┘ │
└────────────────────────────┬────────────────────────────────┘
                             │ OpenDSSDirect.py
┌────────────────────────────▼────────────────────────────────┐
│                    EPRI OpenDSS Engine                       │
│         (Open Distribution System Simulator)                 │
└─────────────────────────────────────────────────────────────┘

opendss-mcp-server/
├── src/opendss_mcp/
│   ├── server.py              # MCP server entry point
│   ├── tools/                 # 7 MCP tools
│   │   ├── feeder_loader.py
│   │   ├── power_flow.py
│   │   ├── voltage_checker.py
│   │   ├── capacity.py
│   │   ├── der_optimizer.py
│   │   ├── timeseries.py
│   │   └── visualization.py
│   ├── utils/                 # Utilities
│   │   ├── dss_wrapper.py     # OpenDSS wrapper
│   │   ├── validators.py      # Input validation
│   │   ├── formatters.py      # Response formatting
│   │   ├── harmonics.py       # Harmonics analysis
│   │   └── inverter_control.py # Smart inverter control
│   └── data/                  # Data files
│       ├── ieee_feeders/      # IEEE 13/34/123 bus systems
│       ├── load_profiles/     # Time-series load profiles
│       └── control_curves/    # Volt-var/volt-watt curves
├── tests/                     # Test suite (41% coverage)
│   ├── test_feeder_loader.py
│   ├── test_power_flow.py
│   ├── test_voltage_checker.py
│   ├── test_capacity.py
│   ├── test_der_optimizer.py
│   ├── test_timeseries.py
│   ├── test_visualization.py
│   └── test_integration.py
├── examples/                  # Example scripts and outputs
│   ├── generate_plots.py
│   ├── plots/                 # Example visualizations
│   └── README.md
├── docs/                      # Complete documentation
│   ├── INSTALLATION.md
│   ├── USER_GUIDE.md
│   └── API_REFERENCE.md
├── pyproject.toml            # Project configuration
└── README.md                 # This file

# Install development dependencies
pip install -e ".[test]"

# Run all tests
pytest

# Run with coverage
pytest --cov=src/opendss_mcp --cov-report=term-missing --cov-report=html

# Run specific test suite
pytest tests/test_integration.py -v

# Run with verbose output
pytest -vv

# Format code with black
black src/ tests/

# Lint with pylint
pylint src/opendss_mcp

# Type checking with mypy
mypy src/opendss_mcp

# Sort imports
isort src/ tests/

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run hooks manually
pre-commit run --all-files

@software{opendss_mcp_server,
  title = {OpenDSS MCP Server: Conversational Power System Analysis with AI},
  author = {El-Shazly, Ahmed},
  year = {2025},
  url = {https://github.com/ahmedelshazly27/opendss-mcp-server},
  version = {1.0.0},
  note = {Model Context Protocol server for EPRI OpenDSS}
}

El-Shazly, A. (2025). OpenDSS MCP Server: Conversational Power System Analysis
with AI (Version 1.0.0) [Computer software].
https://github.com/ahmedelshazly27/opendss-mcp-server

A. El-Shazly, "OpenDSS MCP Server: Conversational Power System Analysis with AI,"
version 1.0.0, 2025. [Online].
Available: https://github.com/ahmedelshazly27/opendss-mcp-server

MIT License

Copyright (c) 2025 Ahmed El-Shazly

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.