OpenDSS MCP 服务器
基于人工智能的对话式电力系统分析
*通过自然语言交互，将分销规划研究时间从数周缩短至数分钟*
](https://badge.fury.io/py/opendss-mcp-server)       
特点/功能 • 安装 • 快速入门 • 文档 • 示例 • 做出贡献
______________________________________________________________________
概述
该 OpenDSS MCP 服务器 这是一个模型上下文协议（MCP）服务器，它将Claude AI与EPRI的OpenDSS电力系统模拟器连接起来。它使配电规划工程师、公用事业公司和研究人员能够通过（该服务器）执行复杂的电力系统分析 对话式自然语言 而不是使用复杂的脚本编写。
问题
传统的配电系统分析需要：
- ⏱️（这个符号本身没有直接的中文翻译，但它通常代表“倒计时”或“时间流逝”的概念，在中文语境中可以理解为“时间飞逝”或“倒计时中”等表达） 2-3周 每项研究
- 复杂的Python/DSS脚本编写
- 📊 手动数据处理
- 🎨 自定义可视化代码
- 📝 详尽的文档
解决方案
使用OpenDSS MCP服务器：
- ⚡（闪电符号，常用于表示快速、能量或惊喜等含义） 30分钟 每项研究（速度快100倍）
- 💬 通过Claude执行自然语言指令
- 🤖 自动分析与洞察
- 📈 自动生成专业可视化图表
- 📋 即时报告生成
示例：
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]______________________________________________________________________
特点
🎯 核心能力
7款全面的MCP工具
- 🔌 IEEE馈线负载
- IEEE 13、34和123节点测试系统 - 官方EPRI测试用例 - 实时电路修改 - 完整的拓扑结构和组件数据
- ⚡ 功率流分析
- 快照模式、每日模式和年度模式 - 收敛性检查 - 谐波频率分析 - 损耗计算和电压分布
- 📊 电压质量评估
- ANSI C84.1标准合规性检查 - 违规行为识别与报告 - 阶段特定分析 - 前后对比
- 🌞 DER（分布式能源资源）布局优化
- 太阳能、电池、风能和电动汽车充电器 - 多重目标（最小化损失、最大化产能、减少违规） - 智能逆变器的电压-无功功率控制 - 候选公交线路对比排名
- 📈 托管容量分析
- 增量容量测试 - 电压和热约束识别 - 生成容量曲线 - 多地点评估
- ⏰ 时间序列模拟
- 每日/季节性负荷曲线 - 太阳能/风能发电模式 - 能量分析（千瓦时，而不仅仅是千瓦） - 收敛跟踪
- 🎨 专业可视化
- 电压曲线条形图 - 网络拓扑图 - 时间序列多面板图 - 容量曲线 - 谐波频谱分析
⚙️ 高级功能
🎼 高次谐波分析
- IEEE 519合规性检查
- 总谐波失真（THD）计算
- 各次谐波的幅值（第3次、第5次、第7次等）
- 频率扫描支持
- 多总线谐波频谱可视化
🔄 智能逆变器控制
- 符合IEEE 1547-2018标准的电压-无功曲线
- 支持加州第21条规则
- 自定义控制曲线定义
- 伏特-瓦特削减（或：电压-功率限制）
- 实时逆变器状态监测
🧪 IEEE测试馈线
- IEEE 13节点系统小型系统，非常适合测试
- IEEE 34节点系统具有多个调节器的中型系统
- IEEE 123节点系统用于全面研究的大型系统
- 经EPRI官方验证的模型
- 包含完整的DSS源文件
🔗 MCP 集成
- 无缝集成Claude桌面版
- 自然语言命令接口
- 自动工具选择
- 结构化的JSON响应
- 错误处理和恢复
______________________________________________________________________
安装
快速安装
# 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!')"Claude 桌面配置
在您的Claude桌面配置文件中添加：
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"opendss": {
"command": "python",
"args": ["-m", "opendss_mcp.server"],
"env": {
"PYTHONPATH": "/absolute/path/to/opendss-mcp-server/src"
}
}
}
}📖 代表“书”或“书籍”的意思。 如需详细的安装说明，请参阅 INSTALLATION.md 翻译为中文是：“安装指南.md” 或者 “安装说明.md”。（注：在中文语境中，“INSTALLATION”通常被翻译为“安装”，而“.md”表示的是Markdown文件格式，因此这里直接保留了“.md”的形式。）
______________________________________________________________________
快速入门
1. 基本潮流分析
问克劳德：
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 kVAr2. 分布式能源资源（DER）整合研究
问克劳德：
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]3. 承载能力评估
问克劳德：
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]4. 时间序列模拟
问克劳德：
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]5. Python API 使用
你也可以直接在Python中使用这些工具：
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]______________________________________________________________________
示例
示例可视化
所有可视化图表均自动生成，并且可以保存为出版质量（300 DPI）：
电压曲线/电压分布： Voltage Profile
网络图： Network Diagram
时间序列分析： Time-Series
承载能力曲线： Capacity Curve
谐波频谱： Harmonics Spectrum
运行示例
# Generate all example plots
cd examples
python generate_plots.py
# Check output in examples/plots/
ls -lh examples/plots/看 示例/README.md（文件名，表示一个包含示例说明的Markdown文件） 以获取详细文档。
______________________________________________________________________
文档
📚 完整的文档套件
🎯 快捷链接
______________________________________________________________________
建筑学
系统概述
┌─────────────────────────────────────────────────────────────┐
│ 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当前测试覆盖率： 41%（持续改进中）
代码质量
# 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/预提交钩子（Pre-commit Hooks）
# Install pre-commit hooks
pip install pre-commit
pre-commit install
# Run hooks manually
pre-commit run --all-files______________________________________________________________________
做出贡献
我们欢迎社区成员的贡献！无论是修复漏洞、添加功能、改进文档，还是分享使用案例，您的帮助都将受到赞赏。
如何贡献（或：如何参与贡献）
- 为仓库创建分支（或：克隆仓库） 在GitHub上
- 创建一个特性分支 (
git checkout -b feature/amazing-feature) - 进行你的更改 带有清晰的提交信息
- 添加测试 用于新功能
- 确保测试通过 (
pytest） - 更新文档 按需
- 提交拉取请求 附有清晰描述
贡献领域
我们特别感兴趣的是以下方面的贡献：
- 🐛 表示“虫子”或“错误（bug）”。 错误修复 以及错误处理的改进
- ✨（闪亮、闪耀的符号，常用于表达喜悦、庆祝或强调） 新功能 （额外工具，分析能力）
- 📖 代表“书籍”或“阅读”的意思。 文档 改进和翻译
- 🧪 翻译为中文是“🧪（化学实验或试管的符号）”。不过，通常我们不会直接翻译这个符号本身，而是根据上下文解释其含义，比如“化学实验”或“试管”。如果需要一个简短的翻译，可以是“试管符号”或“化学实验符号”。但在这里，为了保持原符号的直观性，直接保留“🧪”并稍作解释。 测试覆盖率 扩张
- 🎨（颜料或绘画的符号） 可视化 增强（或改进）
- 🌍 表示“地球”，可以翻译为“地球”或“世界”。 实际应用案例 以及示例
- 🔧（扳手或工具的符号，常用于表示需要修理或工具的场景） 演出 优化
代码风格
- 跟随 PEP 8（Python增强提案第8号） 风格指南
- 使用 类型提示 对于所有函数
- 写 谷歌风格的文档字符串（docstrings）
- 最大行长度： 100个字符
- 使用 黑色 用于代码格式化
- 目标 pylint 评分 > 8.0
测试指南
- 为所有新功能编写测试
- 保持或提高代码覆盖率
- 使用描述性的测试名称
- 包括正向和负向测试用例
- 测试错误处理路径
报告问题
请使用 GitHub Issues 来报告错误或请求功能。请包含：
- 描述 关于该问题或功能请求
- 复现步骤 （用于错误/漏洞）
- 预期行为 与实际行为相比
- 环境详情 (操作系统，Python版本，OpenDSS版本)
- 错误信息 以及堆栈跟踪
- 最小可复现示例 （如适用）
______________________________________________________________________
引用
如果您在学术研究中使用OpenDSS MCP服务器，请引用：
BibTeX
@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}
}APA格式
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-serverIEEE 格式
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______________________________________________________________________
致谢
使用了（或“基于”）
- EPRI OpenDSS（美国电力研究协会开放配电系统仿真器） - 开放分布式系统模拟器
- OpenDSSDirect.py 翻译成中文可以是“OpenDSSDirect.py（保持原名，因通常不翻译编程语言或库名）”或者直接说明其为“用于电力系统仿真的OpenDSS接口Python库”。不过，由于“OpenDSSDirect.py”本身是一个专有名词，直接翻译可能失去其原意，因此在实际应用中，我们通常保留原名，并在必要时进行解释说明 - Python与OpenDSS的接口
- Anthropic MCP（注：此处“MCP”可能是一个特定术语或缩写，根据上下文可能有不同的含义，但在此直接翻译为“MCP”，若需具体含义需结合上下文或专业领域解释） - 模型上下文协议
- 克劳德人工智能 - 对话式人工智能界面
IEEE测试馈线
这个项目使用了官方的IEEE测试馈线：
- IEEE 13节点测试馈线 - IEEE配电测试馈线工作组
- IEEE 34节点测试馈线 - IEEE配电测试馈线工作组
- IEEE 123节点测试馈线 - IEEE配电测试馈线工作组
来源： IEEE PES测试馈线
______________________________________________________________________
许可证
这个项目遵循以下许可协议： 麻省理工学院许可证（MIT License） - 看见 许可证 文件中有详细信息。
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.______________________________________________________________________
支持
寻求帮助
- 文档： 从……开始 USER_GUIDE.md 翻译为中文是：“用户指南.md”
- 问题： 报告错误至
- 讨论： 参与关于……的讨论
联系
- 作者 艾哈迈德·埃尔-沙兹利
- 电子邮件： ahmedelshazly27@示例.com（注：原文中的“example.com”在实际使用中应替换为真实的邮件域名，此处保留“example.com”是为了说明翻译格式）
- GitHub： @ahmedelshazly27（用户名，可译为“艾哈迈德·埃尔沙兹利27”或保持原样，根据上下文决定是否需要具体翻译用户名）
______________________________________________________________________
路线图
版本1.1（计划于2026年第一季度发布）
- \[ \] 额外的IEEE测试馈线（8500节点，欧洲低压）
- \[ \] 保护配合分析
- \[ \] 故障电流计算
- \[ \] 可靠性指标（SAIDI，SAIFI）
- \[ \] 多进料器优化
版本1.2（计划于2026年第二季度发布）
- \[ \] 实时SCADA集成
- \[ \] 电池储能优化
- \[ \] 电动汽车整合
- \[ \] 需求响应建模
- \[ \] 微电网与孤岛分析
2.0版本（计划于2026年第三季度发布）
- \[ \] 网页应用的REST API
- \[ \] 控制面板和网页用户界面
- \[ \] 多用户协作
- \[ \] 支持云部署
- \[ \] 高级机器学习集成
______________________________________________________________________
⚡ 一次一条馈线，加速可再生能源转型 ⚡
为全球电力系统工程师倾心打造