OpenDSS MCP 服务器

MCP 服务器，允许 Claude 使用 OpenDSS 通过 OpenDSSDirect.py 库对中压/低压配电网络（医院、建筑、关键设施）进行建模和仿真。

1. 安装

要求：Python 3.10 或更高版本。

cd opendss-mcp
python3 -m venv venv
source venv/bin/activate        # En Windows: venv\Scripts\activate
pip install -r requirements.txt

验证所有内容都能正确导入：

python3 -c "import opendssdirect; import mcp; print('OK')"

Related MCP server: uam-analyst

2. 独立测试服务器（可选但推荐）

在将其连接到 Claude 之前，你可以直接使用附带的研究案例测试逻辑：

python3 examples/hospital_basico.py

如果你看到 "convergio": true 且电压标幺值接近 1.0，则服务器工作正常。该脚本模拟了一个带有中压进线、配电变压器、手术室配电盘（关键负载）和 N-1 应急分析的医院——完整细节请参见 examples/hospital_basico.py 中的代码。

3. 连接到 Claude Desktop

打开（或创建）Claude Desktop 的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加此条目（调整绝对路径到你保存项目的位置）：

{
  "mcpServers": {
    "opendss": {
      "command": "/ruta/absoluta/a/opendss-mcp/venv/bin/python3",
      "args": ["/ruta/absoluta/a/opendss-mcp/server.py"]
    }
  }
}

在 Windows 上，venv 的 Python 可执行文件路径通常是 ...\opendss-mcp\venv\Scripts\python.exe。

完全重启 Claude Desktop。你应该会看到工具图标（🔨）并列出 "opendss" 作为已连接的服务器。

4. 可用工具

5. 与 Claude 的对话式使用示例

连接后，你可以要求 Claude 做类似的事情：

“模拟一个医院，带有 13.2 kV 进线、一个 500 kVA 变压器降至 0.4 kV、一个 50 kW 关键手术室配电盘和一个 20 kW 照明配电盘。运行潮流计算，并告诉我电压是否在正常范围（±5%）内。”

或者用于应急分析：

“模拟如果主低压线路丢失会发生什么。医院的手术室配电盘会断电吗？”

或者用于可视化网络：

“生成当前电路的单线图，并在浏览器中打开它。”

5.1 可视化示例

examples/visualizar_hospital.py 构建了相同的医院模型，并生成两个 HTML 图：一个在正常条件下，另一个在 N-1 应急条件下，以便直观比较失去手术室馈线的影响。

python3 examples/visualizar_hospital.py

每个母线都绘制为一条水平条，根据其标幺电压着色（绿色：0.95–1.05 pu，黄色：0.90–1.10 pu，红色：超出范围或失压）。变压器、负载（如果是关键负载则为红色）和发电机使用专用符号绘制——这不是通用图形，而是采用真实电气工程惯例的单线图。如果在生成图表之前模拟了 N-1 应急，相应的开关会在网络中发生故障的确切位置显示为打开（带有间隙和“ABIERTO”标签）。

5.2 研究案例：多配电盘园区

examples/campus_hospitalario.py 模拟了更接近真实医院的情况：一个中压进线为三个独立变压器（手术室、住院部、行政）供电，每个变压器带有多个自身负载，外加一个专门用于最关键配电盘的备用发电机。它还对一个变压器（不仅仅是线路）进行了 N-1 分析。

python3 examples/campus_hospitalario.py

生成的图表（diagrama_campus.html）已经视觉上区分了：母线（圆形，按电压着色）、变压器（铜色虚线）、负载（方形——如果是关键负载则为红色）和发电机（蓝色菱形），以及一个侧面板，显示电路摘要（损耗、收敛性、元件计数）。

6. 重要技术说明

• 电压基准（VoltageBases）：OpenDSS 要求显式声明网络的电压等级（Set VoltageBases=[...] 和 CalcVoltageBases），以便正确计算标幺值。服务器在每次添加变压器时都会自动执行此操作——在正常使用中你无需担心。

• 持久性：模型在 MCP 服务器进程运行期间驻留在内存中。如果关闭 Claude Desktop，模型将丢失。要保存模型，你可以要求 Claude 使用 obtener_netlist() 并导出生成的 .dss 脚本。

• 当前限制：服务器假设三相平衡网络，以简化多个默认参数（R1/X1）。要模拟精细的不平衡（在单相/两相低压中常见），可以扩展工具以包含零序参数（R0/X0）和阻抗矩阵——此初始版本未包含。

• ⚠ calcular_arc_flash 是简化方法（Lee/IEEE 1584-2002），不是 IEEE 1584-2018 的完整经验模型。 完整模型的回归表是 IEEE 受保护标准的一部分，此处未实现。Lee 方法对于学习物理和估算数量级很有用，但往往对封闭柜内设备偏保守（高估），并且清除时间作为输入数据给出（不是从实际保护 TCC 曲线计算，此 MCP 也尚未模拟）。切勿使用这些结果来确定实际设施中的个人防护装备（EPP）——这需要由合格电气工程师审查的规范研究（ETAP 或其他验证软件）。

7. 变更历史

参见 CHANGELOG.md 了解每个版本中添加了哪些工具、应用的修正以及 OpenDSS 中尚未覆盖的元素（LoadShape、PVSystem、Storage、Capacitor、小时分析、谐波、拓扑可视化等）。此项目以增量方式扩展，一次一个研究案例。